author | sspitsyn |
Fri, 14 Jun 2013 15:17:10 -0700 | |
changeset 18081 | c0a9e6c4058c |
parent 14571 | 1e4d36113875 |
child 19553 | 9bbd930be684 |
permissions | -rw-r--r-- |
1 | 1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
2 |
<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> |
|
3 |
<!-- |
|
14287 | 4 |
Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved. |
1 | 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 |
||
5547
f4b087cbb361
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
1
diff
changeset
|
21 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
f4b087cbb361
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
1
diff
changeset
|
22 |
or visit www.oracle.com if you need additional information or have any |
f4b087cbb361
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
1
diff
changeset
|
23 |
questions. |
1 | 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 |
||
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
283 |
<!ELEMENT vmspec EMPTY> |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
284 |
<!ATTLIST vmspec chapter CDATA #IMPLIED> |
1 | 285 |
|
286 |
<!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*> |
|
287 |
<!ATTLIST internallink id CDATA #REQUIRED> |
|
288 |
||
289 |
<!ELEMENT functionphaselist EMPTY> |
|
290 |
<!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED> |
|
291 |
||
292 |
<!ELEMENT eventphaselist EMPTY> |
|
293 |
<!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED> |
|
294 |
||
295 |
<!ELEMENT issue ANY> |
|
296 |
||
297 |
<!ELEMENT rationale ANY> |
|
298 |
||
299 |
<!ELEMENT todo ANY> |
|
300 |
||
301 |
<!ELEMENT origin (#PCDATA)*> |
|
302 |
||
303 |
<!ELEMENT elide (intro|function|callback|event)*> |
|
304 |
<!ATTLIST elide why CDATA #IMPLIED> |
|
305 |
||
306 |
<!ELEMENT constants (constant*)> |
|
307 |
<!ATTLIST constants id CDATA #REQUIRED |
|
308 |
label CDATA #REQUIRED |
|
309 |
kind (enum|bits|const) #REQUIRED |
|
310 |
since CDATA "1.0"> |
|
311 |
||
312 |
<!ELEMENT constant ANY> |
|
313 |
<!ATTLIST constant id CDATA #REQUIRED |
|
314 |
num CDATA #REQUIRED> |
|
315 |
||
316 |
<!ELEMENT tm (#PCDATA)> |
|
317 |
||
318 |
<!ELEMENT i (#PCDATA|jvmti|tm)*> |
|
319 |
||
320 |
<!ELEMENT b (#PCDATA|jvmti|code)*> |
|
321 |
||
322 |
<!ELEMENT code (#PCDATA|space)*> |
|
323 |
||
324 |
<!ELEMENT pre ANY> |
|
325 |
||
326 |
<!ELEMENT space EMPTY> |
|
327 |
||
328 |
<!ELEMENT jvmti EMPTY> |
|
329 |
||
330 |
<!ELEMENT example (#PCDATA|i)*> |
|
331 |
||
332 |
<!ELEMENT br EMPTY> |
|
333 |
||
334 |
<!ELEMENT p EMPTY> |
|
335 |
||
336 |
<!ELEMENT dl (dt|dd)+> |
|
337 |
||
338 |
<!ELEMENT dd ANY> |
|
339 |
||
340 |
<!ELEMENT dt (#PCDATA|jvmti|code|i|b)*> |
|
341 |
||
342 |
<!ELEMENT table (tr)+> |
|
343 |
||
344 |
<!ELEMENT tr (td|th)*> |
|
345 |
||
346 |
<!ELEMENT td ANY> |
|
347 |
<!ATTLIST td align (left|right|center) "center"> |
|
348 |
||
349 |
<!ELEMENT th ANY> |
|
350 |
<!ATTLIST th align (left|right|center) "center"> |
|
351 |
||
352 |
<!ELEMENT ul (li)+> |
|
353 |
<!ATTLIST ul type (disc|circle|square) "disc"> |
|
354 |
||
355 |
<!ELEMENT li ANY> |
|
356 |
]> |
|
357 |
||
358 |
<specification label="JVM(TM) Tool Interface" |
|
359 |
majorversion="1" |
|
7413 | 360 |
minorversion="2" |
14287 | 361 |
microversion="2"> |
1 | 362 |
<title subtitle="Version"> |
363 |
<tm>JVM</tm> Tool Interface |
|
364 |
</title> |
|
365 |
||
366 |
<intro id="whatIs" label="What is the JVM Tool Interface?"> |
|
367 |
The <tm>JVM</tm> Tool Interface (<jvmti/>) |
|
368 |
is a programming interface used by development and monitoring tools. |
|
369 |
It provides both a way to inspect the state and |
|
370 |
to control the execution of applications running in the |
|
371 |
<tm>Java</tm> virtual machine (VM). |
|
372 |
<p/> |
|
373 |
<jvmti/> is intended to provide a VM interface for the full breadth of tools |
|
374 |
that need access to VM state, including but not limited to: profiling, |
|
375 |
debugging, monitoring, thread analysis, and coverage analysis tools. |
|
376 |
<p/> |
|
377 |
<jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual |
|
378 |
machine. |
|
379 |
<p/> |
|
380 |
<jvmti/> is a two-way interface. |
|
381 |
A client of <jvmti/>, hereafter called an <i>agent</i>, |
|
382 |
can be notified of |
|
383 |
interesting occurrences through <internallink id="EventSection">events</internallink>. |
|
384 |
<jvmti/> |
|
385 |
can query and control the application through many |
|
386 |
<internallink id="FunctionSection">functions</internallink>, |
|
387 |
either in response to events or |
|
388 |
independent of them. |
|
389 |
<p/> |
|
390 |
Agents run in the same process with and communicate directly with |
|
391 |
the virtual machine executing |
|
392 |
the application being examined. This communication is |
|
393 |
through a native interface (<jvmti/>). The native in-process interface allows |
|
394 |
maximal control with minimal intrusion on the part of a tool. |
|
395 |
Typically, agents are relatively compact. They can be controlled |
|
396 |
by a separate process which implements the bulk of a tool's |
|
397 |
function without interfering with the target application's normal execution. |
|
398 |
</intro> |
|
399 |
||
400 |
<intro id="architecture" label="Architecture"> |
|
401 |
Tools can be written directly to <jvmti/> or indirectly |
|
402 |
through higher level interfaces. |
|
403 |
The Java Platform Debugger Architecture includes <jvmti/>, but also |
|
404 |
contains higher-level, out-of-process debugger interfaces. The higher-level |
|
405 |
interfaces are more appropriate than <jvmti/> for many tools. |
|
406 |
For more information on the Java Platform Debugger Architecture, |
|
407 |
see the |
|
14287 | 408 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java |
1 | 409 |
Platform Debugger Architecture website</externallink>. |
410 |
</intro> |
|
411 |
||
412 |
<intro id="writingAgents" label="Writing Agents"> |
|
413 |
Agents can be written in any native language that supports C |
|
414 |
language calling conventions and C or C++ |
|
415 |
definitions. |
|
416 |
<p/> |
|
417 |
The function, event, data type, and constant definitions needed for |
|
418 |
using <jvmti/> are defined in the include file <code>jvmti.h</code>. |
|
419 |
To use these definitions add the <tm>J2SE</tm> include directory |
|
420 |
to your include path and add |
|
421 |
<example> |
|
422 |
#include <jvmti.h> |
|
423 |
</example> |
|
424 |
to your source code. |
|
425 |
</intro> |
|
426 |
||
427 |
<intro id="deployingAgents" label="Deploying Agents"> |
|
428 |
An agent is deployed in a platform specific manner but is typically the |
|
429 |
platform equivalent of a dynamic library. On the <tm>Windows</tm> operating |
|
430 |
system, for example, an agent library is a "Dynamic Linked Library" (DLL). |
|
431 |
On the <tm>Solaris</tm> Operating Environment, an agent library is a shared |
|
432 |
object (<code>.so</code> file). |
|
433 |
<p/> |
|
434 |
An agent may be started at VM startup by specifying the agent library |
|
435 |
name using a <internallink id="starting">command line option</internallink>. |
|
436 |
Some implementations may support a mechanism to <internallink id="onattach"> |
|
437 |
start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. |
|
438 |
The details of how this is initiated are implementation specific. |
|
439 |
</intro> |
|
440 |
||
441 |
<intro id="starting" label="Agent Command Line Options"> |
|
442 |
The term "command-line option" is used below to |
|
443 |
mean options supplied in the <code>JavaVMInitArgs</code> argument |
|
444 |
to the <code>JNI_CreateJavaVM</code> function of the JNI |
|
445 |
Invocation API. |
|
446 |
<p/> |
|
447 |
One of the two following |
|
448 |
command-line options is used on VM startup to |
|
449 |
properly load and run agents. |
|
450 |
These arguments identify the library containing |
|
451 |
the agent as well as an options |
|
452 |
string to be passed in at startup. |
|
453 |
<dl> |
|
454 |
<dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> |
|
455 |
<dd> |
|
456 |
The name following <code>-agentlib:</code> is the name of the |
|
457 |
library to load. Lookup of the library, both its full name and location, |
|
458 |
proceeds in a platform-specific manner. |
|
459 |
Typically, the <i><agent-lib-name></i> is expanded to an |
|
460 |
operating system specific file name. |
|
461 |
The <i><options></i> will be passed to the agent on start-up. |
|
462 |
For example, if the option |
|
463 |
<code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to |
|
464 |
load the shared library <code>foo.dll</code> from the system <code>PATH</code> |
|
465 |
under <tm>Windows</tm> or <code>libfoo.so</code> from the |
|
466 |
<code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. |
|
467 |
</dd> |
|
468 |
<dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> |
|
469 |
<dd> |
|
470 |
The path following <code>-agentpath:</code> is the absolute path from which |
|
471 |
to load the library. |
|
472 |
No library name expansion will occur. |
|
473 |
The <i><options></i> will be passed to the agent on start-up. |
|
474 |
For example, if the option |
|
475 |
<code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to |
|
476 |
load the shared library <code>c:\myLibs\foo.dll</code>. |
|
477 |
</dd> |
|
478 |
</dl> |
|
479 |
The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
|
480 |
in the library will be invoked. |
|
481 |
<p/> |
|
482 |
Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> |
|
483 |
will be searched for JNI native method implementations to facilitate the |
|
484 |
use of Java programming language code in tools, as is needed for |
|
485 |
<internallink id="bci">bytecode instrumentation</internallink>. |
|
486 |
<p/> |
|
487 |
The agent libraries will be searched after all other libraries have been |
|
488 |
searched (agents wishing to override or intercept the native method |
|
489 |
implementations of non-agent methods can use the |
|
490 |
<eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>). |
|
491 |
<p/> |
|
492 |
These switches do the above and nothing more - they do not change the |
|
493 |
state of the VM or <jvmti/>. No command line options are needed |
|
494 |
to enable <jvmti/> |
|
495 |
or aspects of <jvmti/>, this is handled programmatically |
|
496 |
by the use of |
|
497 |
<internallink id="capability">capabilities</internallink>. |
|
498 |
</intro> |
|
499 |
||
500 |
<intro id="startup" label="Agent Start-Up"> |
|
501 |
The VM starts each agent by invoking a start-up function. |
|
502 |
If the agent is started in the <code>OnLoad</code> |
|
503 |
<functionlink id="GetPhase">phase</functionlink> the function |
|
504 |
<internallink id="onload"><code>Agent_OnLoad</code></internallink> |
|
505 |
will be invoked. |
|
506 |
If the agent is started in the live |
|
507 |
<functionlink id="GetPhase">phase</functionlink> the function |
|
508 |
<internallink id="onattach"><code>Agent_OnAttach</code></internallink> |
|
509 |
will be invoked. |
|
510 |
Exactly one call to a start-up function is made per agent. |
|
511 |
</intro> |
|
512 |
||
513 |
<intro id="onload" label="Agent Start-Up (OnLoad phase)"> |
|
514 |
If an agent is started during the <code>OnLoad</code> phase then its |
|
515 |
agent library must export a start-up function with the following prototype: |
|
516 |
<example> |
|
517 |
JNIEXPORT jint JNICALL |
|
518 |
Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> |
|
519 |
The VM will start the agent by calling this function. |
|
520 |
It will be called early enough in VM initialization that: |
|
521 |
<ul> |
|
522 |
<li><functionlink id="SetSystemProperty">system properties</functionlink> |
|
523 |
may be set before they have been used in the start-up of the VM</li> |
|
524 |
<li>the full set of |
|
525 |
<internallink id="capability">capabilities</internallink> |
|
526 |
is still available (note that capabilities that configure the VM |
|
527 |
may only be available at this time--see the |
|
528 |
<internallink id="capability">Capability function section</internallink>)</li> |
|
529 |
<li>no bytecodes have executed</li> |
|
530 |
<li>no classes have been loaded</li> |
|
531 |
<li>no objects have been created</li> |
|
532 |
</ul> |
|
533 |
<p/> |
|
534 |
The VM will call the <code>Agent_OnLoad</code> function with |
|
535 |
<i><options></i> as the second argument - |
|
536 |
that is, using the command-line option examples, |
|
537 |
<code>"opt1,opt2"</code> will be passed to the <code>char *options</code> |
|
538 |
argument of <code>Agent_OnLoad</code>. |
|
539 |
The <code>options</code> argument is encoded as a |
|
540 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
541 |
If <i>=<options></i> is not specified, |
|
542 |
a zero length string is passed to <code>options</code>. |
|
543 |
The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code> |
|
544 |
call. If needed beyond this time the string or parts of the string must |
|
545 |
be copied. |
|
546 |
The period between when <code>Agent_OnLoad</code> is called and when it |
|
547 |
returns is called the <i>OnLoad phase</i>. |
|
548 |
Since the VM is not initialized during the OnLoad |
|
549 |
<functionlink id="GetPhase">phase</functionlink>, |
|
550 |
the set of allowed operations |
|
551 |
inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the |
|
552 |
functionality available at this time). |
|
553 |
The agent can safely process the options and set |
|
554 |
event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once |
|
555 |
the VM initialization event is received |
|
556 |
(that is, the <eventlink id="VMInit">VMInit</eventlink> |
|
557 |
callback is invoked), the agent |
|
558 |
can complete its initialization. |
|
559 |
<rationale> |
|
560 |
Early startup is required so that agents can set the desired capabilities, |
|
561 |
many of which must be set before the VM is initialized. |
|
562 |
In JVMDI, the -Xdebug command-line option provided |
|
563 |
very coarse-grain control of capabilities. |
|
564 |
JVMPI implementations use various tricks to provide a single "JVMPI on" switch. |
|
565 |
No reasonable command-line |
|
566 |
option could provide the fine-grain of control required to balance needed capabilities vs |
|
567 |
performance impact. |
|
568 |
Early startup is also needed so that agents can control the execution |
|
569 |
environment - modifying the file system and system properties to install |
|
570 |
their functionality. |
|
571 |
</rationale> |
|
572 |
<p/> |
|
573 |
The return value from <code>Agent_OnLoad</code> is used to indicate an error. |
|
574 |
Any value other than zero indicates an error and causes termination of the VM. |
|
575 |
</intro> |
|
576 |
||
577 |
<intro id="onattach" label="Agent Start-Up (Live phase)"> |
|
578 |
A VM may support a mechanism that allows agents to be started in the VM during the live |
|
579 |
<functionlink id="GetPhase">phase</functionlink>. The details of how this is supported, |
|
580 |
are implementation specific. For example, a tool may use some platform specific mechanism, |
|
581 |
or implementation specific API, to attach to the running VM, and request it start a given |
|
582 |
agent. |
|
583 |
<p/> |
|
584 |
If an agent is started during the live phase then its agent library |
|
585 |
must export a start-up function |
|
586 |
with the following prototype: |
|
587 |
<example> |
|
588 |
JNIEXPORT jint JNICALL |
|
589 |
Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> |
|
590 |
<p/> |
|
591 |
The VM will start the agent by calling this function. |
|
592 |
It will be called in the context of a thread |
|
593 |
that is attached to the VM. The first argument <i><vm></i> is the Java VM. |
|
594 |
The <i><options></i> argument is the startup options provided to the agent. |
|
595 |
<i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 |
|
596 |
</internallink> string. |
|
597 |
If startup options were not provided, a zero length string is passed to |
|
598 |
<code>options</code>. The lifespan of the <code>options</code> string is the |
|
599 |
<code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of |
|
600 |
the string must be copied. |
|
601 |
<p/> |
|
602 |
Note that some <internallink id="capability">capabilities</internallink> |
|
603 |
may not be available in the live phase. |
|
604 |
<p/> |
|
605 |
The <code>Agent_OnAttach</code> function initializes the agent and returns a value |
|
606 |
to the VM to indicate if an error occurred. Any value other than zero indicates an error. |
|
607 |
An error does not cause the VM to terminate. Instead the VM ignores the error, or takes |
|
608 |
some implementation specific action -- for example it might print an error to standard error, |
|
609 |
or record the error in a system log. |
|
610 |
</intro> |
|
611 |
||
612 |
<intro id="onunload" label="Agent Shutdown"> |
|
613 |
The library may optionally export a |
|
614 |
shutdown function with the following prototype: |
|
615 |
<example> |
|
616 |
JNIEXPORT void JNICALL |
|
617 |
Agent_OnUnload(JavaVM *vm)</example> |
|
618 |
This function will be called by the VM when the library is about to be unloaded. |
|
619 |
The library will be unloaded and this function will be called if some platform specific |
|
620 |
mechanism causes the unload (an unload mechanism is not specified in this document) |
|
621 |
or the library is (in effect) unloaded by the termination of the VM whether through |
|
622 |
normal termination or VM failure, including start-up failure. |
|
623 |
Uncontrolled shutdown is, of couse, an exception to this rule. |
|
624 |
Note the distinction between this function and the |
|
625 |
<eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event |
|
626 |
to be sent, the VM must have run at least to the point of initialization and a valid |
|
627 |
<jvmti/> environment must exist which has set a callback for VMDeath |
|
628 |
and enabled the event |
|
629 |
None of these are required for <code>Agent_OnUnload</code> and this function |
|
630 |
is also called if the library is unloaded for other reasons. |
|
631 |
In the case that a VM Death event is sent, it will be sent before this |
|
632 |
function is called (assuming this function is called due to VM termination). |
|
633 |
This function can be used to clean-up resources allocated by the agent. |
|
634 |
</intro> |
|
635 |
||
636 |
<intro id="tooloptions" label="JAVA_TOOL_OPTIONS"> |
|
637 |
Since the command-line cannot always be accessed or modified, for example in embedded VMs |
|
638 |
or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is |
|
639 |
provided so that agents may be launched in these cases. |
|
640 |
<p/> |
|
641 |
Platforms which support environment variables or other named strings, may support the |
|
642 |
<code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space |
|
643 |
boundaries. White-space characters include space, tab, carriage-return, new-line, |
|
644 |
vertical-tab, and form-feed. Sequences of white-space characters are considered |
|
645 |
equivalent to a single white-space character. No white-space is included in the options |
|
646 |
unless quoted. Quoting is as follows: |
|
647 |
<ul> |
|
648 |
<li>All characters enclosed between a pair of single quote marks (''), except a single |
|
649 |
quote, are quoted.</li> |
|
650 |
<li>Double quote characters have no special meaning inside a pair of single quote marks.</li> |
|
651 |
<li>All characters enclosed between a pair of double quote marks (""), except a double |
|
652 |
quote, are quoted.</li> |
|
653 |
<li>Single quote characters have no special meaning inside a pair of double quote marks.</li> |
|
654 |
<li>A quoted part can start or end anywhere in the variable.</li> |
|
655 |
<li>White-space characters have no special meaning when quoted -- they are included in |
|
656 |
the option like any other character and do not mark white-space boundaries.</li> |
|
657 |
<li>The pair of quote marks is not included in the option.</li> |
|
658 |
</ul> |
|
659 |
<code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied |
|
660 |
in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is |
|
661 |
a concern; for example, the Reference Implementation disables this feature on Unix systems when |
|
662 |
the effective user or group ID differs from the real ID. |
|
663 |
This feature is intended to support the initialization of tools -- specifically including the |
|
664 |
launching of native or Java programming language agents. Multiple tools may wish to use this |
|
665 |
feature, so the variable should not be overwritten, instead, options should be appended to |
|
666 |
the variable. Note that since the variable is processed at the time of the JNI Invocation |
|
667 |
API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled. |
|
668 |
</intro> |
|
669 |
||
670 |
<intro id="environments" label="Environments"> |
|
671 |
The <jvmti/> specification supports the use of multiple simultaneous |
|
672 |
<jvmti/> agents. |
|
673 |
Each agent has its own <jvmti/> environment. |
|
674 |
That is, the <jvmti/> state is |
|
675 |
separate for each agent - changes to one environment do not affect the |
|
676 |
others. The state of a <jvmti/> |
|
677 |
environment includes: |
|
678 |
<ul> |
|
679 |
<li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li> |
|
680 |
<li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li> |
|
681 |
<li><internallink id="capability">the capabilities</internallink></li> |
|
682 |
<li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li> |
|
683 |
</ul> |
|
684 |
Although their <jvmti/> state |
|
685 |
is separate, agents inspect and modify the shared state |
|
686 |
of the VM, they also share the native environment in which they execute. |
|
687 |
As such, an agent can perturb the results of other agents or cause them |
|
688 |
to fail. It is the responsibility of the agent writer to specify the level |
|
689 |
of compatibility with other agents. <jvmti/> implementations are not capable |
|
690 |
of preventing destructive interactions between agents. Techniques to reduce |
|
691 |
the likelihood of these occurrences are beyond the scope of this document. |
|
692 |
<p/> |
|
693 |
An agent creates a <jvmti/> environment |
|
694 |
by passing a <jvmti/> version |
|
695 |
as the interface ID to the JNI Invocation API function |
|
14287 | 696 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>. |
1 | 697 |
See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink> |
698 |
for more details on the creation and use of |
|
699 |
<jvmti/> environments. |
|
700 |
Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from |
|
701 |
<internallink id="onload"><code>Agent_OnLoad</code></internallink>. |
|
702 |
</intro> |
|
703 |
||
704 |
<intro id="bci" label="Bytecode Instrumentation"> |
|
705 |
This interface does not include some events that one might expect in an interface with |
|
706 |
profiling support. Some examples include object allocation events and full speed |
|
707 |
method enter and exit events. The interface instead provides support for |
|
708 |
<i>bytecode instrumentation</i>, the ability to alter the Java virtual machine |
|
709 |
bytecode instructions which comprise the target program. Typically, these alterations |
|
710 |
are to add "events" to the code of a method - for example, to add, at the beginning of a method, |
|
711 |
a call to <code>MyProfiler.methodEntered()</code>. |
|
712 |
Since the changes are purely additive, they do not modify application |
|
713 |
state or behavior. |
|
714 |
Because the inserted agent code is standard bytecodes, the VM can run at full speed, |
|
715 |
optimizing not only the target program but also the instrumentation. If the |
|
716 |
instrumentation does not involve switching from bytecode execution, no expensive |
|
717 |
state transitions are needed. The result is high performance events. |
|
718 |
This approach also provides complete control to the agent: instrumentation can be |
|
719 |
restricted to "interesting" portions of the code (e.g., the end user's code) and |
|
720 |
can be conditional. Instrumentation can run entirely in Java programming language |
|
721 |
code or can call into the native agent. Instrumentation can simply maintain |
|
722 |
counters or can statistically sample events. |
|
723 |
<p/> |
|
724 |
Instrumentation can be inserted in one of three ways: |
|
725 |
<ul> |
|
726 |
<li> |
|
727 |
Static Instrumentation: The class file is instrumented before it |
|
728 |
is loaded into the VM - for example, by creating a duplicate directory of |
|
729 |
<code>*.class</code> files which have been modified to add the instrumentation. |
|
730 |
This method is extremely awkward and, in general, an agent cannot know |
|
731 |
the origin of the class files which will be loaded. |
|
732 |
</li> |
|
733 |
<li> |
|
734 |
Load-Time Instrumentation: When a class file is loaded by the VM, the raw |
|
735 |
bytes of the class file are sent for instrumentation to the agent. |
|
736 |
The <eventlink id="ClassFileLoadHook"/> |
|
737 |
event, triggered by the class load, |
|
738 |
provides this functionality. This mechanism provides efficient |
|
739 |
and complete access to one-time instrumentation. |
|
740 |
</li> |
|
741 |
<li> |
|
742 |
Dynamic Instrumentation: A class which is already loaded (and possibly |
|
743 |
even running) is modified. This optional feature is provided by the |
|
744 |
<eventlink id="ClassFileLoadHook"/> event, triggered by calling the |
|
745 |
<functionlink id="RetransformClasses"/> function. |
|
746 |
Classes can be modified multiple times and can be returned to their |
|
747 |
original state. |
|
748 |
The mechanism allows instrumentation which changes during the |
|
749 |
course of execution. |
|
750 |
</li> |
|
751 |
</ul> |
|
752 |
<p/> |
|
753 |
The class modification functionality provided in this interface |
|
754 |
is intended to provide a mechanism for instrumentation |
|
755 |
(the <eventlink id="ClassFileLoadHook"/> event |
|
756 |
and the <functionlink id="RetransformClasses"/> function) |
|
757 |
and, during development, for fix-and-continue debugging |
|
758 |
(the <functionlink id="RedefineClasses"/> function). |
|
759 |
<p/> |
|
760 |
Care must be taken to avoid perturbing dependencies, especially when |
|
761 |
instrumenting core classes. For example, an approach to getting notification |
|
762 |
of every object allocation is to instrument the constructor on |
|
763 |
<code>Object</code>. Assuming that the constructor is initially |
|
764 |
empty, the constructor could be changed to: |
|
765 |
<example> |
|
766 |
public Object() { |
|
767 |
MyProfiler.allocationTracker(this); |
|
768 |
} |
|
769 |
</example> |
|
770 |
However, if this change was made using the |
|
771 |
<eventlink id="ClassFileLoadHook"/> |
|
772 |
event then this might impact a typical VM as follows: |
|
773 |
the first created object will call the constructor causing a class load of |
|
774 |
<code>MyProfiler</code>; which will then cause |
|
775 |
object creation, and since <code>MyProfiler</code> isn't loaded yet, |
|
776 |
infinite recursion; resulting in a stack overflow. A refinement of this |
|
777 |
would be to delay invoking the tracking method until a safe time. For |
|
778 |
example, <code>trackAllocations</code> could be set in the |
|
779 |
handler for the <code>VMInit</code> event. |
|
780 |
<example> |
|
781 |
static boolean trackAllocations = false; |
|
782 |
||
783 |
public Object() { |
|
784 |
if (trackAllocations) { |
|
785 |
MyProfiler.allocationTracker(this); |
|
786 |
} |
|
787 |
} |
|
788 |
</example> |
|
789 |
<p/> |
|
790 |
The <functionlink id="SetNativeMethodPrefix"/> allows native methods |
|
791 |
to be instrumented by the use of wrapper methods. |
|
792 |
</intro> |
|
793 |
||
794 |
<intro id="mUTF" label="Modified UTF-8 String Encoding"> |
|
795 |
<jvmti/> uses modified UTF-8 to encode character strings. |
|
796 |
This is the same encoding used by JNI. |
|
797 |
Modified UTF-8 differs |
|
798 |
from standard UTF-8 in the representation of supplementary characters |
|
799 |
and of the null character. See the |
|
14287 | 800 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542"> |
1 | 801 |
Modified UTF-8 Strings</externallink> |
802 |
section of the JNI specification for details. |
|
803 |
</intro> |
|
804 |
||
805 |
<intro id="context" label="Specification Context"> |
|
806 |
Since this interface provides access to the state of applications running in the |
|
807 |
Java virtual machine; |
|
808 |
terminology refers to the Java platform and not the native |
|
809 |
platform (unless stated otherwise). For example: |
|
810 |
<ul> |
|
811 |
<li>"thread" means Java programming language thread.</li> |
|
812 |
<li>"stack frame" means Java virtual machine stack frame.</li> |
|
813 |
<li>"class" means Java programming language class.</li> |
|
814 |
<li>"heap" means Java virtual machine heap.</li> |
|
815 |
<li>"monitor" means Java programming language object monitor.</li> |
|
816 |
</ul> |
|
817 |
<p/> |
|
818 |
Sun, Sun Microsystems, the Sun logo, Java, and JVM |
|
5547
f4b087cbb361
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
1
diff
changeset
|
819 |
are trademarks or registered trademarks of Oracle |
f4b087cbb361
6941466: Oracle rebranding changes for Hotspot repositories
trims
parents:
1
diff
changeset
|
820 |
and/or its affiliates, in the U.S. and other countries. |
1 | 821 |
</intro> |
822 |
||
823 |
||
824 |
<functionsection label="Functions"> |
|
825 |
<intro id="jvmtiEnvAccess" label="Accessing Functions"> |
|
826 |
Native code accesses <jvmti/> features |
|
827 |
by calling <jvmti/> functions. |
|
828 |
Access to <jvmti/> functions is by use of an interface pointer |
|
829 |
in the same manner as |
|
14287 | 830 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java |
1 | 831 |
Native Interface (JNI) functions</externallink> are accessed. |
832 |
The <jvmti/> interface pointer is called the |
|
833 |
<i>environment pointer</i>. |
|
834 |
<p/> |
|
835 |
An environment pointer is a pointer to an environment and has |
|
836 |
the type <code>jvmtiEnv*</code>. |
|
837 |
An environment has information about its <jvmti/> connection. |
|
838 |
The first value in the environment is a pointer to the function table. |
|
839 |
The function table is an array of pointers to <jvmti/> functions. |
|
840 |
Every function pointer is at a predefined offset inside the |
|
841 |
array. |
|
842 |
<p/> |
|
843 |
When used from the C language: |
|
844 |
double indirection is used to access the functions; |
|
845 |
the environment pointer provides context and is the first |
|
846 |
parameter of each function call; for example: |
|
847 |
<example> |
|
848 |
jvmtiEnv *jvmti; |
|
849 |
... |
|
850 |
jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes); |
|
851 |
</example> |
|
852 |
<p/> |
|
853 |
When used from the C++ language: |
|
854 |
functions are accessed as member functions of <code>jvmtiEnv</code>; |
|
855 |
the environment pointer is not passed to the function call; for example: |
|
856 |
<example> |
|
857 |
jvmtiEnv *jvmti; |
|
858 |
... |
|
859 |
jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes); |
|
860 |
</example> |
|
861 |
Unless otherwise stated, all examples and declarations in this |
|
862 |
specification use the C language. |
|
863 |
<p/> |
|
864 |
A <jvmti/> environment can be obtained through the JNI Invocation API |
|
865 |
<code>GetEnv</code> function: |
|
866 |
<example> |
|
867 |
jvmtiEnv *jvmti; |
|
868 |
... |
|
869 |
(*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0); |
|
870 |
</example> |
|
871 |
Each call to <code>GetEnv</code> |
|
872 |
creates a new <jvmti/> connection and thus |
|
873 |
a new <jvmti/> environment. |
|
874 |
The <code>version</code> argument of <code>GetEnv</code> must be |
|
875 |
a <jvmti/> version. |
|
876 |
The returned environment may have a different version than the |
|
877 |
requested version but the returned environment must be compatible. |
|
878 |
<code>GetEnv</code> will return <code>JNI_EVERSION</code> if a |
|
879 |
compatible version is not available, if <jvmti/> is not supported or |
|
880 |
<jvmti/> is not supported in the current VM configuration. |
|
881 |
Other interfaces may be added for creating <jvmti/> environments |
|
882 |
in specific contexts. |
|
883 |
Each environment has its own state (for example, |
|
884 |
<functionlink id="SetEventNotificationMode">desired events</functionlink>, |
|
885 |
<functionlink id="SetEventCallbacks">event handling functions</functionlink>, and |
|
886 |
<functionlink id="AddCapabilities">capabilities</functionlink>). |
|
887 |
An environment is released with |
|
888 |
<functionlink id="DisposeEnvironment"></functionlink>. |
|
889 |
Thus, unlike JNI which has one environment per thread, <jvmti/> environments work |
|
890 |
across threads and are created dynamically. |
|
891 |
</intro> |
|
892 |
||
893 |
<intro id="functionReturn" label="Function Return Values"> |
|
894 |
<jvmti/> functions always return an |
|
895 |
<internallink id="ErrorSection">error code</internallink> via the |
|
896 |
<datalink id="jvmtiError"/> function return value. |
|
897 |
Some functions can return additional |
|
898 |
values through pointers provided by the calling function. |
|
899 |
In some cases, <jvmti/> functions allocate memory that your program must |
|
900 |
explicitly deallocate. This is indicated in the individual <jvmti/> |
|
901 |
function descriptions. Empty lists, arrays, sequences, etc are |
|
902 |
returned as <code>NULL</code>. |
|
903 |
<p/> |
|
904 |
In the event that the <jvmti/> function encounters |
|
905 |
an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values |
|
906 |
of memory referenced by argument pointers is undefined, but no memory |
|
907 |
will have been allocated and no global references will have been allocated. |
|
908 |
If the error occurs because of invalid input, no action will have occurred. |
|
909 |
</intro> |
|
910 |
||
911 |
<intro id="refs" label="Managing JNI Object References"> |
|
912 |
<jvmti/> functions identify objects with JNI references |
|
913 |
(<datalink id="jobject"/> and <datalink id="jclass"/>) |
|
914 |
and their derivatives |
|
915 |
(<datalink id="jthread"/> and <datalink id="jthreadGroup"/>). |
|
916 |
References passed to |
|
917 |
<jvmti/> functions can be either global or local, but they must be |
|
918 |
strong references. All references returned by <jvmti/> functions are |
|
919 |
local references--these local references are created |
|
920 |
during the <jvmti/> call. |
|
921 |
Local references are a resource that must be managed (see the |
|
14287 | 922 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>). |
1 | 923 |
When threads return from native code all local references |
924 |
are freed. Note that some threads, including typical |
|
925 |
agent threads, will never return from native code. |
|
926 |
A thread is ensured the ability to create sixteen local |
|
927 |
references without the need for any explicit management. |
|
928 |
For threads executing a limited number of <jvmti/> calls before |
|
929 |
returning from native code |
|
930 |
(for example, threads processing events), |
|
931 |
it may be determined that no explicit management |
|
932 |
is needed. |
|
933 |
However, long running agent threads will need explicit |
|
934 |
local reference management--usually with the JNI functions |
|
935 |
<code>PushLocalFrame</code> and <code>PopLocalFrame</code>. |
|
936 |
Conversely, to preserve references beyond the |
|
937 |
return from native code, they must be converted to global references. |
|
938 |
These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> |
|
939 |
as they are not <datalink id="jobject"/>s. |
|
940 |
</intro> |
|
941 |
||
942 |
<intro id="prereqState" label="Prerequisite State for Calling Functions"> |
|
943 |
Unless the function explicitly states that the agent must bring |
|
944 |
a thread or the VM to a particular state (for example, suspended), |
|
945 |
the <jvmti/> implementation is responsible for bringing the VM to a |
|
946 |
safe and consistent state for performing the function. |
|
947 |
</intro> |
|
948 |
||
949 |
<intro id="functionsExceptions" label="Exceptions and Functions"> |
|
950 |
<jvmti/> functions never throw exceptions; error conditions are |
|
951 |
communicated via the |
|
952 |
<internallink id="functionReturn">function return value</internallink>. |
|
953 |
Any existing exception state is preserved across a call to a |
|
954 |
<jvmti/> function. |
|
955 |
See the |
|
956 |
<externallink |
|
14287 | 957 |
id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770" |
1 | 958 |
>Java Exceptions</externallink> |
959 |
section of the JNI specification for information on handling exceptions. |
|
960 |
</intro> |
|
961 |
||
962 |
<category id="memory" label="Memory Management"> |
|
963 |
<intro> |
|
964 |
These functions provide for the allocation and deallocation of |
|
965 |
memory used by <jvmti/> functionality and can be used to provide |
|
966 |
working memory for agents. |
|
967 |
Memory managed by <jvmti/> is not compatible with other memory |
|
968 |
allocation libraries and mechanisms. |
|
969 |
</intro> |
|
970 |
||
971 |
<function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46"> |
|
972 |
<synopsis>Allocate</synopsis> |
|
973 |
<description> |
|
974 |
Allocate an area of memory through the <jvmti/> allocator. |
|
975 |
The allocated |
|
976 |
memory should be freed with <functionlink id="Deallocate"></functionlink>. |
|
977 |
</description> |
|
978 |
<origin>jvmdi</origin> |
|
979 |
<capabilities> |
|
980 |
</capabilities> |
|
981 |
<parameters> |
|
982 |
<param id="size"> |
|
983 |
<jlong/> |
|
984 |
<description> |
|
985 |
The number of bytes to allocate. |
|
986 |
<rationale> |
|
987 |
<code>jlong</code> is used for compatibility with JVMDI. |
|
988 |
</rationale> |
|
989 |
</description> |
|
990 |
</param> |
|
991 |
<param id="mem_ptr"> |
|
992 |
<allocbuf incount="size"><uchar/></allocbuf> |
|
993 |
<description> |
|
994 |
On return, a pointer to the beginning of the allocated memory. |
|
995 |
If <code>size</code> is zero, <code>NULL</code> is returned. |
|
996 |
</description> |
|
997 |
</param> |
|
998 |
</parameters> |
|
999 |
<errors> |
|
1000 |
<error id="JVMTI_ERROR_OUT_OF_MEMORY"> |
|
1001 |
Memory request cannot be honored. |
|
1002 |
</error> |
|
1003 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
1004 |
<paramlink id="size"></paramlink> is less than zero. |
|
1005 |
</error> |
|
1006 |
</errors> |
|
1007 |
</function> |
|
1008 |
||
1009 |
<function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47"> |
|
1010 |
<synopsis>Deallocate</synopsis> |
|
1011 |
<description> |
|
1012 |
Deallocate <code>mem</code> using the <jvmti/> allocator. |
|
1013 |
This function should |
|
1014 |
be used to deallocate any memory allocated and returned |
|
1015 |
by a <jvmti/> function |
|
1016 |
(including memory allocated with <functionlink id="Allocate"></functionlink>). |
|
1017 |
All allocated memory must be deallocated |
|
1018 |
or the memory cannot be reclaimed. |
|
1019 |
</description> |
|
1020 |
<origin>jvmdi</origin> |
|
1021 |
<capabilities> |
|
1022 |
</capabilities> |
|
1023 |
<parameters> |
|
1024 |
<param id="mem"> |
|
1025 |
<outbuf> |
|
1026 |
<uchar/> |
|
1027 |
<nullok>the call is ignored</nullok> |
|
1028 |
</outbuf> |
|
1029 |
<description> |
|
1030 |
A pointer to the beginning of the allocated memory. |
|
1031 |
Please ignore "On return, the elements are set." |
|
1032 |
<todo>keep it from generating "On return, the elements are set"</todo> |
|
1033 |
</description> |
|
1034 |
</param> |
|
1035 |
</parameters> |
|
1036 |
<errors> |
|
1037 |
</errors> |
|
1038 |
</function> |
|
1039 |
</category> |
|
1040 |
||
1041 |
<category id="threadCategory" label="Thread"> |
|
1042 |
<intro> |
|
1043 |
</intro> |
|
1044 |
||
1045 |
<function id="GetThreadState" num="17"> |
|
1046 |
<synopsis>Get Thread State</synopsis> |
|
1047 |
<description> |
|
1048 |
Get the state of a thread. The state of the thread is represented by the |
|
1049 |
answers to the hierarchical set of questions below: |
|
1050 |
<ul type="circle"> |
|
1051 |
<li><i>Alive?</i> |
|
1052 |
<ul> |
|
1053 |
<li>Not alive. |
|
1054 |
<ul type="circle"> |
|
1055 |
<li><i>Why not alive?</i> |
|
1056 |
<ul> |
|
1057 |
<li>New.</li> |
|
1058 |
<li>Terminated (<datalink |
|
1059 |
id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li> |
|
1060 |
</ul> |
|
1061 |
</li> |
|
1062 |
</ul> |
|
1063 |
</li> |
|
1064 |
<li>Alive (<datalink |
|
1065 |
id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>) |
|
1066 |
<ul type="circle"> |
|
1067 |
<li><i>Suspended?</i> |
|
1068 |
<ul> |
|
1069 |
<li>Suspended (<datalink |
|
1070 |
id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li> |
|
1071 |
<li>Not suspended</li> |
|
1072 |
</ul> |
|
1073 |
</li> |
|
1074 |
<li><i>Interrupted?</i> |
|
1075 |
<ul> |
|
1076 |
<li>Interrupted (<datalink |
|
1077 |
id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li> |
|
1078 |
<li>Not interrupted.</li> |
|
1079 |
</ul> |
|
1080 |
</li> |
|
1081 |
<li><i>In native?</i> |
|
1082 |
<ul> |
|
1083 |
<li>In native code (<datalink |
|
1084 |
id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li> |
|
1085 |
<li>In Java programming language code</li> |
|
1086 |
</ul> |
|
1087 |
</li> |
|
1088 |
<li><i>What alive state?</i> |
|
1089 |
<ul> |
|
1090 |
<li>Runnable (<datalink |
|
1091 |
id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li> |
|
1092 |
<li>Blocked (<datalink |
|
1093 |
id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li> |
|
1094 |
<li>Waiting (<datalink |
|
1095 |
id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>) |
|
1096 |
<ul type="circle"> |
|
1097 |
<li><i>Timed wait?</i> |
|
1098 |
<ul> |
|
1099 |
<li>Indefinite (<datalink |
|
1100 |
id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li> |
|
1101 |
<li>Timed (<datalink |
|
1102 |
id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li> |
|
1103 |
</ul> |
|
1104 |
</li> |
|
1105 |
<li><i>Why waiting?</i> |
|
1106 |
<ul> |
|
1107 |
<li>Object.wait (<datalink |
|
1108 |
id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li> |
|
1109 |
<li>LockSupport.park (<datalink |
|
1110 |
id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li> |
|
1111 |
<li>Sleeping (<datalink |
|
1112 |
id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li> |
|
1113 |
</ul> |
|
1114 |
</li> |
|
1115 |
</ul> |
|
1116 |
</li> |
|
1117 |
</ul> |
|
1118 |
</li> |
|
1119 |
</ul> |
|
1120 |
</li> |
|
1121 |
</ul> |
|
1122 |
</li> |
|
1123 |
</ul> |
|
1124 |
<p/> |
|
1125 |
The answers are represented by the following bit vector. |
|
1126 |
<constants id="jvmtiThreadState" label="Thread State Flags" kind="bits"> |
|
1127 |
<constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001"> |
|
1128 |
Thread is alive. Zero if thread is new (not started) or terminated. |
|
1129 |
</constant> |
|
1130 |
<constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002"> |
|
1131 |
Thread has completed execution. |
|
1132 |
</constant> |
|
1133 |
<constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004"> |
|
1134 |
Thread is runnable. |
|
1135 |
</constant> |
|
1136 |
<constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400"> |
|
1137 |
Thread is waiting to enter a synchronization block/method or, |
|
1138 |
after an <code>Object.wait()</code>, waiting to re-enter a |
|
1139 |
synchronization block/method. |
|
1140 |
</constant> |
|
1141 |
<constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080"> |
|
1142 |
Thread is waiting. |
|
1143 |
</constant> |
|
1144 |
<constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010"> |
|
1145 |
Thread is waiting without a timeout. |
|
1146 |
For example, <code>Object.wait()</code>. |
|
1147 |
</constant> |
|
1148 |
<constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020"> |
|
1149 |
Thread is waiting with a maximum time to wait specified. |
|
1150 |
For example, <code>Object.wait(long)</code>. |
|
1151 |
</constant> |
|
1152 |
<constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040"> |
|
1153 |
Thread is sleeping -- <code>Thread.sleep(long)</code>. |
|
1154 |
</constant> |
|
1155 |
<constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100"> |
|
1156 |
Thread is waiting on an object monitor -- <code>Object.wait</code>. |
|
1157 |
</constant> |
|
1158 |
<constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200"> |
|
1159 |
Thread is parked, for example: <code>LockSupport.park</code>, |
|
1160 |
<code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>. |
|
1161 |
</constant> |
|
1162 |
<constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000"> |
|
1163 |
Thread suspended. |
|
1164 |
<code>java.lang.Thread.suspend()</code> |
|
1165 |
or a <jvmti/> suspend function |
|
1166 |
(such as <functionlink id="SuspendThread"></functionlink>) |
|
1167 |
has been called on the thread. If this bit |
|
1168 |
is set, the other bits refer to the thread state before suspension. |
|
1169 |
</constant> |
|
1170 |
<constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000"> |
|
1171 |
Thread has been interrupted. |
|
1172 |
</constant> |
|
1173 |
<constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000"> |
|
1174 |
Thread is in native code--that is, a native method is running |
|
1175 |
which has not called back into the VM or Java programming |
|
1176 |
language code. |
|
1177 |
<p/> |
|
1178 |
This flag is not set when running VM compiled Java programming |
|
1179 |
language code nor is it set when running VM code or |
|
1180 |
VM support code. Native VM interface functions, such as JNI and |
|
1181 |
<jvmti/> functions, may be implemented as VM code. |
|
1182 |
</constant> |
|
1183 |
<constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000"> |
|
1184 |
Defined by VM vendor. |
|
1185 |
</constant> |
|
1186 |
<constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000"> |
|
1187 |
Defined by VM vendor. |
|
1188 |
</constant> |
|
1189 |
<constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000"> |
|
1190 |
Defined by VM vendor. |
|
1191 |
</constant> |
|
1192 |
</constants> |
|
1193 |
The following definitions are used to convert <jvmti/> thread state |
|
1194 |
to <code>java.lang.Thread.State</code> style states. |
|
1195 |
<constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits"> |
|
1196 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK" |
|
1197 |
num="JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> |
|
1198 |
Mask the state with this before comparison |
|
1199 |
</constant> |
|
1200 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW" |
|
1201 |
num="0"> |
|
1202 |
<code>java.lang.Thread.State.NEW</code> |
|
1203 |
</constant> |
|
1204 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED" |
|
1205 |
num="JVMTI_THREAD_STATE_TERMINATED"> |
|
1206 |
<code>java.lang.Thread.State.TERMINATED</code> |
|
1207 |
</constant> |
|
1208 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE" |
|
1209 |
num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE"> |
|
1210 |
<code>java.lang.Thread.State.RUNNABLE</code> |
|
1211 |
</constant> |
|
1212 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED" |
|
1213 |
num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"> |
|
1214 |
<code>java.lang.Thread.State.BLOCKED</code> |
|
1215 |
</constant> |
|
1216 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING" |
|
1217 |
num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY"> |
|
1218 |
<code>java.lang.Thread.State.WAITING</code> |
|
1219 |
</constant> |
|
1220 |
<constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING" |
|
1221 |
num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"> |
|
1222 |
<code>java.lang.Thread.State.TIMED_WAITING</code> |
|
1223 |
</constant> |
|
1224 |
</constants> |
|
1225 |
<b>Rules</b> |
|
1226 |
<p/> |
|
1227 |
There can be no more than one answer to a question, although there can be no |
|
1228 |
answer (because the answer is unknown, does not apply, or none of the answers is |
|
1229 |
correct). An answer is set only when the enclosing answers match. |
|
1230 |
That is, no more than one of |
|
1231 |
<ul type="circle"> |
|
1232 |
<li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li> |
|
1233 |
<li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li> |
|
1234 |
<li><code>JVMTI_THREAD_STATE_WAITING</code></li> |
|
1235 |
</ul> |
|
1236 |
can be set (a <tm>J2SE</tm> compliant implementation will always set |
|
1237 |
one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). |
|
1238 |
And if any of these are set, the enclosing answer |
|
1239 |
<code>JVMTI_THREAD_STATE_ALIVE</code> is set. |
|
1240 |
No more than one of |
|
1241 |
<ul type="circle"> |
|
1242 |
<li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li> |
|
1243 |
<li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li> |
|
1244 |
</ul> |
|
1245 |
can be set (a <tm>J2SE</tm> compliant implementation will always set |
|
1246 |
one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). |
|
1247 |
And if either is set, the enclosing answers |
|
1248 |
<code>JVMTI_THREAD_STATE_ALIVE</code> and |
|
1249 |
<code>JVMTI_THREAD_STATE_WAITING</code> are set. |
|
1250 |
No more than one of |
|
1251 |
<ul type="circle"> |
|
1252 |
<li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li> |
|
1253 |
<li><code>JVMTI_THREAD_STATE_PARKED</code></li> |
|
1254 |
<li><code>JVMTI_THREAD_STATE_SLEEPING</code></li> |
|
1255 |
</ul> |
|
1256 |
can be set. And if any of these is set, the enclosing answers |
|
1257 |
<code>JVMTI_THREAD_STATE_ALIVE</code> and |
|
1258 |
<code>JVMTI_THREAD_STATE_WAITING</code> are set. |
|
1259 |
Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set, |
|
1260 |
then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set. |
|
1261 |
If a state <i>A</i> is implemented using the mechanism of |
|
1262 |
state <i>B</i> then it is state <i>A</i> which |
|
1263 |
is returned by this function. |
|
1264 |
For example, if <code>Thread.sleep(long)</code> |
|
1265 |
is implemented using <code>Object.wait(long)</code> |
|
1266 |
then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code> |
|
1267 |
which is returned. |
|
1268 |
More than one of |
|
1269 |
<ul type="circle"> |
|
1270 |
<li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li> |
|
1271 |
<li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li> |
|
1272 |
<li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li> |
|
1273 |
</ul> |
|
1274 |
can be set, but if any is set, |
|
1275 |
<code>JVMTI_THREAD_STATE_ALIVE</code> is set. |
|
1276 |
<p/> |
|
1277 |
And finally, |
|
1278 |
<code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless |
|
1279 |
<code>JVMTI_THREAD_STATE_ALIVE</code> is not set. |
|
1280 |
<p/> |
|
1281 |
The thread state representation is designed for extension in future versions |
|
1282 |
of the specification; thread state values should be used accordingly, that is |
|
1283 |
they should not be used as ordinals. |
|
1284 |
Most queries can be made by testing a single bit, if use in a switch statement is desired, |
|
1285 |
the state bits should be masked with the interesting bits. |
|
1286 |
All bits not defined above are reserved for future use. |
|
1287 |
A VM, compliant to the current specification, must set reserved bits to zero. |
|
1288 |
An agent should ignore reserved bits -- |
|
1289 |
they should not be assumed to be zero and thus should not be included in comparisons. |
|
1290 |
<p/> |
|
1291 |
<b>Examples</b> |
|
1292 |
<p/> |
|
1293 |
Note that the values below exclude reserved and vendor bits. |
|
1294 |
<p/> |
|
1295 |
The state of a thread blocked at a <code>synchronized</code>-statement would be: |
|
1296 |
<example> |
|
1297 |
JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER |
|
1298 |
</example> |
|
1299 |
The state of a thread which hasn't started yet would be: |
|
1300 |
<example> |
|
1301 |
0 |
|
1302 |
</example> |
|
1303 |
The state of a thread at a <code>Object.wait(3000)</code> would be: |
|
1304 |
<example> |
|
1305 |
JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + |
|
1306 |
JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + |
|
1307 |
JVMTI_THREAD_STATE_MONITOR_WAITING |
|
1308 |
</example> |
|
1309 |
The state of a thread suspended while runnable would be: |
|
1310 |
<example> |
|
1311 |
JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED |
|
1312 |
</example> |
|
1313 |
<p/> |
|
1314 |
<b>Testing the State</b> |
|
1315 |
<p/> |
|
1316 |
In most cases, the thread state can be determined by testing the one bit corresponding |
|
1317 |
to that question. For example, the code to test if a thread is sleeping: |
|
1318 |
<example> |
|
1319 |
jint state; |
|
1320 |
jvmtiError err; |
|
1321 |
||
1322 |
err = (*jvmti)->GetThreadState(jvmti, thread, &state); |
|
1323 |
if (err == JVMTI_ERROR_NONE) { |
|
1324 |
if (state & JVMTI_THREAD_STATE_SLEEPING) { ... |
|
1325 |
</example> |
|
1326 |
<p/> |
|
1327 |
For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be: |
|
1328 |
<example> |
|
1329 |
if (state & JVMTI_THREAD_STATE_WAITING) { ... |
|
1330 |
</example> |
|
1331 |
For some states, more than one bit will need to be tested as is the case |
|
1332 |
when testing if a thread has not yet been started: |
|
1333 |
<example> |
|
1334 |
if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ... |
|
1335 |
</example> |
|
1336 |
To distinguish timed from untimed <code>Object.wait</code>: |
|
1337 |
<example> |
|
1338 |
if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) { |
|
1339 |
if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) { |
|
1340 |
printf("in Object.wait(long timeout)\n"); |
|
1341 |
} else { |
|
1342 |
printf("in Object.wait()\n"); |
|
1343 |
} |
|
1344 |
} |
|
1345 |
</example> |
|
1346 |
<p/> |
|
1347 |
<b>Relationship to <code>java.lang.Thread.State</code></b> |
|
1348 |
<p/> |
|
1349 |
The thread state represented by <code>java.lang.Thread.State</code> |
|
1350 |
returned from <code>java.lang.Thread.getState()</code> is a subset of the |
|
1351 |
information returned from this function. |
|
1352 |
The corresponding <code>java.lang.Thread.State</code> can be determined |
|
1353 |
by using the provided conversion masks. |
|
1354 |
For example, this returns the name of the <code>java.lang.Thread.State</code> thread state: |
|
1355 |
<example> |
|
1356 |
err = (*jvmti)->GetThreadState(jvmti, thread, &state); |
|
1357 |
abortOnError(err); |
|
1358 |
switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) { |
|
1359 |
case JVMTI_JAVA_LANG_THREAD_STATE_NEW: |
|
1360 |
return "NEW"; |
|
1361 |
case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED: |
|
1362 |
return "TERMINATED"; |
|
1363 |
case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE: |
|
1364 |
return "RUNNABLE"; |
|
1365 |
case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED: |
|
1366 |
return "BLOCKED"; |
|
1367 |
case JVMTI_JAVA_LANG_THREAD_STATE_WAITING: |
|
1368 |
return "WAITING"; |
|
1369 |
case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING: |
|
1370 |
return "TIMED_WAITING"; |
|
1371 |
} |
|
1372 |
</example> |
|
1373 |
</description> |
|
1374 |
<origin>new</origin> |
|
1375 |
<capabilities> |
|
1376 |
</capabilities> |
|
1377 |
<parameters> |
|
1378 |
<param id="thread"> |
|
1379 |
<jthread null="current" started="maybe" impl="noconvert"/> |
|
1380 |
<description> |
|
1381 |
The thread to query. |
|
1382 |
</description> |
|
1383 |
</param> |
|
1384 |
<param id="thread_state_ptr"> |
|
1385 |
<outptr><jint/></outptr> |
|
1386 |
<description> |
|
1387 |
On return, points to state flags, |
|
1388 |
as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>. |
|
1389 |
</description> |
|
1390 |
</param> |
|
1391 |
</parameters> |
|
1392 |
<errors> |
|
1393 |
</errors> |
|
1394 |
</function> |
|
1395 |
||
1396 |
<function id="GetCurrentThread" phase="start" num="18" since="1.1"> |
|
1397 |
<synopsis>Get Current Thread</synopsis> |
|
1398 |
<description> |
|
1399 |
Get the current thread. |
|
1400 |
The current thread is the Java programming language thread which has called the function. |
|
1401 |
<p/> |
|
1402 |
Note that most <jvmti/> functions that take a thread |
|
1403 |
as an argument will accept <code>NULL</code> to mean |
|
1404 |
the current thread. |
|
1405 |
</description> |
|
1406 |
<origin>new</origin> |
|
1407 |
<capabilities> |
|
1408 |
</capabilities> |
|
1409 |
<parameters> |
|
1410 |
<param id="thread_ptr"> |
|
1411 |
<outptr><jthread/></outptr> |
|
1412 |
<description> |
|
1413 |
On return, points to the current thread. |
|
1414 |
</description> |
|
1415 |
</param> |
|
1416 |
</parameters> |
|
1417 |
<errors> |
|
1418 |
</errors> |
|
1419 |
</function> |
|
1420 |
||
1421 |
<function id="GetAllThreads" num="4"> |
|
1422 |
<synopsis>Get All Threads</synopsis> |
|
1423 |
<description> |
|
1424 |
Get all live threads. |
|
1425 |
The threads are Java programming language threads; |
|
1426 |
that is, threads that are attached to the VM. |
|
1427 |
A thread is live if <code>java.lang.Thread.isAlive()</code> |
|
1428 |
would return <code>true</code>, that is, the thread has |
|
1429 |
been started and has not yet died. |
|
1430 |
The universe of threads is determined by the context of the <jvmti/> |
|
1431 |
environment, which typically is all threads attached to the VM. |
|
1432 |
Note that this includes <jvmti/> agent threads |
|
1433 |
(see <functionlink id="RunAgentThread"/>). |
|
1434 |
</description> |
|
1435 |
<origin>jvmdi</origin> |
|
1436 |
<capabilities> |
|
1437 |
</capabilities> |
|
1438 |
<parameters> |
|
1439 |
<param id="threads_count_ptr"> |
|
1440 |
<outptr><jint/></outptr> |
|
1441 |
<description> |
|
1442 |
On return, points to the number of running threads. |
|
1443 |
</description> |
|
1444 |
</param> |
|
1445 |
<param id="threads_ptr"> |
|
1446 |
<allocbuf outcount="threads_count_ptr"><jthread/></allocbuf> |
|
1447 |
<description> |
|
1448 |
On return, points to an array of references, one |
|
1449 |
for each running thread. |
|
1450 |
</description> |
|
1451 |
</param> |
|
1452 |
</parameters> |
|
1453 |
<errors> |
|
1454 |
</errors> |
|
1455 |
</function> |
|
1456 |
||
1457 |
<function id="SuspendThread" num="5"> |
|
1458 |
<synopsis>Suspend Thread</synopsis> |
|
1459 |
<description> |
|
1460 |
Suspend the specified thread. If the calling thread is specified, |
|
1461 |
this function will not return until some other thread calls |
|
1462 |
<functionlink id="ResumeThread"></functionlink>. |
|
1463 |
If the thread is currently suspended, this function |
|
1464 |
does nothing and returns an error. |
|
1465 |
</description> |
|
1466 |
<origin>jvmdi</origin> |
|
1467 |
<capabilities> |
|
1468 |
<required id="can_suspend"></required> |
|
1469 |
</capabilities> |
|
1470 |
<parameters> |
|
1471 |
<param id="thread"> |
|
1472 |
<jthread null="current"/> |
|
1473 |
<description> |
|
1474 |
The thread to suspend. |
|
1475 |
</description> |
|
1476 |
</param> |
|
1477 |
</parameters> |
|
1478 |
<errors> |
|
1479 |
<error id="JVMTI_ERROR_THREAD_SUSPENDED"> |
|
1480 |
Thread already suspended. |
|
1481 |
</error> |
|
1482 |
</errors> |
|
1483 |
</function> |
|
1484 |
||
1485 |
<elide> |
|
1486 |
<function id="SuspendAllThreads" num="101"> |
|
1487 |
<synopsis>Suspend All Threads</synopsis> |
|
1488 |
<description> |
|
1489 |
<issue> |
|
1490 |
There has been no explicit call for this function, and it will |
|
1491 |
thus be removed if there is no interest. |
|
1492 |
</issue> |
|
1493 |
Suspend all live threads except: |
|
1494 |
<ul> |
|
1495 |
<li>already suspended threads</li> |
|
1496 |
<li>those listed in <paramlink id="except_list"></paramlink></li> |
|
1497 |
<li>certain system (non application) threads, as determined |
|
1498 |
by the VM implementation</li> |
|
1499 |
</ul> |
|
1500 |
The threads are Java programming language threads; |
|
1501 |
native threads which are not attached to the VM are not |
|
1502 |
Java programming language threads. |
|
1503 |
A thread is live if <code>java.lang.Thread.isAlive()</code> |
|
1504 |
would return <code>true</code>, that is, the thread has |
|
1505 |
been started and has not yet died. |
|
1506 |
The universe of threads is determined |
|
1507 |
by the context of the <jvmti/> |
|
1508 |
environment, which, typically, is all threads attached to the VM, |
|
1509 |
except critical VM internal threads and <jvmti/> agent threads |
|
1510 |
(see <functionlink id="RunAgentThread"/>). |
|
1511 |
<p/> |
|
1512 |
If the calling thread is specified, |
|
1513 |
all other threads are suspended first then the caller thread is suspended - |
|
1514 |
this function will not return until some other thread calls |
|
1515 |
<functionlink id="ResumeThread"></functionlink>. |
|
1516 |
<p/> |
|
1517 |
The list of actually |
|
1518 |
suspended threads is returned in |
|
1519 |
<paramlink id="suspended_list_ptr"></paramlink>. |
|
1520 |
Suspension is as defined in <functionlink id="SuspendThread"></functionlink>. |
|
1521 |
<functionlink id="ResumeThreadList"></functionlink> |
|
1522 |
can be used to resume the suspended threads. |
|
1523 |
</description> |
|
1524 |
<origin>new</origin> |
|
1525 |
<capabilities> |
|
1526 |
<required id="can_suspend"></required> |
|
1527 |
</capabilities> |
|
1528 |
<parameters> |
|
1529 |
<param id="except_count"> |
|
1530 |
<jint min="0"/> |
|
1531 |
<description> |
|
1532 |
The number of threads in the list of threads not to be suspended. |
|
1533 |
</description> |
|
1534 |
</param> |
|
1535 |
<param id="except_list"> |
|
1536 |
<inbuf incount="except_count"> |
|
1537 |
<jthread/> |
|
1538 |
<nullok>not an error if <code>except_count == 0</code></nullok> |
|
1539 |
</inbuf> |
|
1540 |
<description> |
|
1541 |
The list of threads not to be suspended. |
|
1542 |
</description> |
|
1543 |
</param> |
|
1544 |
<param id="suspended_count_ptr"> |
|
1545 |
<outptr><jint/></outptr> |
|
1546 |
<description> |
|
1547 |
On return, points to the number of threads suspended by this call. |
|
1548 |
</description> |
|
1549 |
</param> |
|
1550 |
<param id="suspended_list_ptr"> |
|
1551 |
<allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf> |
|
1552 |
<description> |
|
1553 |
On return, points to an array of references, one |
|
1554 |
for each thread suspended. |
|
1555 |
</description> |
|
1556 |
</param> |
|
1557 |
</parameters> |
|
1558 |
<errors> |
|
1559 |
<error id="JVMTI_ERROR_INVALID_THREAD"> |
|
1560 |
A thread in <paramlink id="except_list"></paramlink> was invalid. |
|
1561 |
</error> |
|
1562 |
<error id="JVMTI_ERROR_NULL_POINTER"> |
|
1563 |
Both <paramlink id="except_list"></paramlink> was <code>NULL</code> |
|
1564 |
and <paramlink id="except_count"></paramlink> was non-zero. |
|
1565 |
</error> |
|
1566 |
</errors> |
|
1567 |
</function> |
|
1568 |
</elide> |
|
1569 |
||
1570 |
<function id="SuspendThreadList" num="92"> |
|
1571 |
<synopsis>Suspend Thread List</synopsis> |
|
1572 |
<description> |
|
1573 |
Suspend the <paramlink id="request_count"></paramlink> |
|
1574 |
threads specified in the |
|
1575 |
<paramlink id="request_list"></paramlink> array. |
|
1576 |
Threads may be resumed with |
|
1577 |
<functionlink id="ResumeThreadList"></functionlink> or |
|
1578 |
<functionlink id="ResumeThread"></functionlink>. |
|
1579 |
If the calling thread is specified in the |
|
1580 |
<paramlink id="request_list"></paramlink> array, this function will |
|
1581 |
not return until some other thread resumes it. |
|
1582 |
Errors encountered in the suspension of a thread |
|
1583 |
are returned in the <paramlink id="results"></paramlink> |
|
1584 |
array, <b>not</b> in the return value of this function. |
|
1585 |
Threads that are currently suspended do not change state. |
|
1586 |
</description> |
|
1587 |
<origin>jvmdi</origin> |
|
1588 |
<capabilities> |
|
1589 |
<required id="can_suspend"></required> |
|
1590 |
</capabilities> |
|
1591 |
<parameters> |
|
1592 |
<param id="request_count"> |
|
1593 |
<jint min="0"/> |
|
1594 |
<description> |
|
1595 |
The number of threads to suspend. |
|
1596 |
</description> |
|
1597 |
</param> |
|
1598 |
<param id="request_list"> |
|
1599 |
<inbuf incount="request_count"><jthread/></inbuf> |
|
1600 |
<description> |
|
1601 |
The list of threads to suspend. |
|
1602 |
</description> |
|
1603 |
</param> |
|
1604 |
<param id="results"> |
|
1605 |
<outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> |
|
1606 |
<description> |
|
1607 |
An agent supplied array of |
|
1608 |
<paramlink id="request_count"></paramlink> elements. |
|
1609 |
On return, filled with the error code for |
|
1610 |
the suspend of the corresponding thread. |
|
1611 |
The error code will be |
|
1612 |
<errorlink id="JVMTI_ERROR_NONE"></errorlink> |
|
1613 |
if the thread was suspended by this call. |
|
1614 |
Possible error codes are those specified |
|
1615 |
for <functionlink id="SuspendThread"></functionlink>. |
|
1616 |
</description> |
|
1617 |
</param> |
|
1618 |
</parameters> |
|
1619 |
<errors> |
|
1620 |
</errors> |
|
1621 |
</function> |
|
1622 |
||
1623 |
<function id="ResumeThread" num="6"> |
|
1624 |
<synopsis>Resume Thread</synopsis> |
|
1625 |
<description> |
|
1626 |
Resume a suspended thread. |
|
1627 |
Any threads currently suspended through |
|
1628 |
a <jvmti/> suspend function (eg. |
|
1629 |
<functionlink id="SuspendThread"></functionlink>) |
|
1630 |
or <code>java.lang.Thread.suspend()</code> |
|
1631 |
will resume execution; |
|
1632 |
all other threads are unaffected. |
|
1633 |
</description> |
|
1634 |
<origin>jvmdi</origin> |
|
1635 |
<capabilities> |
|
1636 |
<required id="can_suspend"></required> |
|
1637 |
</capabilities> |
|
1638 |
<parameters> |
|
1639 |
<param id="thread"> |
|
1640 |
<jthread/> |
|
1641 |
<description> |
|
1642 |
The thread to resume. |
|
1643 |
</description> |
|
1644 |
</param> |
|
1645 |
</parameters> |
|
1646 |
<errors> |
|
1647 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
1648 |
Thread was not suspended. |
|
1649 |
</error> |
|
1650 |
<error id="JVMTI_ERROR_INVALID_TYPESTATE"> |
|
1651 |
The state of the thread has been modified, and is now inconsistent. |
|
1652 |
</error> |
|
1653 |
</errors> |
|
1654 |
</function> |
|
1655 |
||
1656 |
<function id="ResumeThreadList" num="93"> |
|
1657 |
<synopsis>Resume Thread List</synopsis> |
|
1658 |
<description> |
|
1659 |
Resume the <paramlink id="request_count"></paramlink> |
|
1660 |
threads specified in the |
|
1661 |
<paramlink id="request_list"></paramlink> array. |
|
1662 |
Any thread suspended through |
|
1663 |
a <jvmti/> suspend function (eg. |
|
1664 |
<functionlink id="SuspendThreadList"></functionlink>) |
|
1665 |
or <code>java.lang.Thread.suspend()</code> |
|
1666 |
will resume execution. |
|
1667 |
</description> |
|
1668 |
<origin>jvmdi</origin> |
|
1669 |
<capabilities> |
|
1670 |
<required id="can_suspend"></required> |
|
1671 |
</capabilities> |
|
1672 |
<parameters> |
|
1673 |
<param id="request_count"> |
|
1674 |
<jint min="0"/> |
|
1675 |
<description> |
|
1676 |
The number of threads to resume. |
|
1677 |
</description> |
|
1678 |
</param> |
|
1679 |
<param id="request_list"> |
|
1680 |
<inbuf incount="request_count"><jthread/></inbuf> |
|
1681 |
<description> |
|
1682 |
The threads to resume. |
|
1683 |
</description> |
|
1684 |
</param> |
|
1685 |
<param id="results"> |
|
1686 |
<outbuf incount="request_count"><enum>jvmtiError</enum></outbuf> |
|
1687 |
<description> |
|
1688 |
An agent supplied array of |
|
1689 |
<paramlink id="request_count"></paramlink> elements. |
|
1690 |
On return, filled with the error code for |
|
1691 |
the resume of the corresponding thread. |
|
1692 |
The error code will be |
|
1693 |
<errorlink id="JVMTI_ERROR_NONE"></errorlink> |
|
1694 |
if the thread was suspended by this call. |
|
1695 |
Possible error codes are those specified |
|
1696 |
for <functionlink id="ResumeThread"></functionlink>. |
|
1697 |
</description> |
|
1698 |
</param> |
|
1699 |
</parameters> |
|
1700 |
<errors> |
|
1701 |
</errors> |
|
1702 |
</function> |
|
1703 |
||
1704 |
<function id="StopThread" num="7"> |
|
1705 |
<synopsis>Stop Thread</synopsis> |
|
1706 |
<description> |
|
1707 |
Send the specified asynchronous exception to the specified thread |
|
1708 |
(similar to <code>java.lang.Thread.stop</code>). |
|
1709 |
Normally, this function is used to kill the specified thread with an |
|
1710 |
instance of the exception <code>ThreadDeath</code>. |
|
1711 |
</description> |
|
1712 |
<origin>jvmdi</origin> |
|
1713 |
<capabilities> |
|
1714 |
<required id="can_signal_thread"></required> |
|
1715 |
</capabilities> |
|
1716 |
<parameters> |
|
1717 |
<param id="thread"> |
|
1718 |
<jthread/> |
|
1719 |
<description> |
|
1720 |
The thread to stop. |
|
1721 |
</description> |
|
1722 |
</param> |
|
1723 |
<param id="exception"> |
|
1724 |
<jobject/> |
|
1725 |
<description> |
|
1726 |
The asynchronous exception object. |
|
1727 |
</description> |
|
1728 |
</param> |
|
1729 |
</parameters> |
|
1730 |
<errors> |
|
1731 |
</errors> |
|
1732 |
</function> |
|
1733 |
||
1734 |
<function id="InterruptThread" num="8"> |
|
1735 |
<synopsis>Interrupt Thread</synopsis> |
|
1736 |
<description> |
|
1737 |
Interrupt the specified thread |
|
1738 |
(similar to <code>java.lang.Thread.interrupt</code>). |
|
1739 |
</description> |
|
1740 |
<origin>jvmdi</origin> |
|
1741 |
<capabilities> |
|
1742 |
<required id="can_signal_thread"></required> |
|
1743 |
</capabilities> |
|
1744 |
<parameters> |
|
1745 |
<param id="thread"> |
|
1746 |
<jthread impl="noconvert"/> |
|
1747 |
<description> |
|
1748 |
The thread to interrupt. |
|
1749 |
</description> |
|
1750 |
</param> |
|
1751 |
</parameters> |
|
1752 |
<errors> |
|
1753 |
</errors> |
|
1754 |
</function> |
|
1755 |
||
1756 |
<function id="GetThreadInfo" num="9"> |
|
1757 |
<synopsis>Get Thread Info</synopsis> |
|
1758 |
<typedef id="jvmtiThreadInfo" label="Thread information structure"> |
|
1759 |
<field id="name"> |
|
1760 |
<allocfieldbuf><char/></allocfieldbuf> |
|
1761 |
<description> |
|
1762 |
The thread name, encoded as a |
|
1763 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
1764 |
</description> |
|
1765 |
</field> |
|
1766 |
<field id="priority"> |
|
1767 |
<jint/> |
|
1768 |
<description> |
|
1769 |
The thread priority. See the thread priority constants: |
|
1770 |
<datalink id="jvmtiThreadPriority"></datalink>. |
|
1771 |
</description> |
|
1772 |
</field> |
|
1773 |
<field id="is_daemon"> |
|
1774 |
<jboolean/> |
|
1775 |
<description> |
|
1776 |
Is this a daemon thread? |
|
1777 |
</description> |
|
1778 |
</field> |
|
1779 |
<field id="thread_group"> |
|
1780 |
<jthreadGroup/> |
|
1781 |
<description> |
|
1782 |
The thread group to which this thread belongs. |
|
1783 |
<code>NULL</code> if the thread has died. |
|
1784 |
</description> |
|
1785 |
</field> |
|
1786 |
<field id="context_class_loader"> |
|
1787 |
<jobject/> |
|
1788 |
<description> |
|
1789 |
The context class loader associated with this thread. |
|
1790 |
</description> |
|
1791 |
</field> |
|
1792 |
</typedef> |
|
1793 |
<description> |
|
1794 |
Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure |
|
1795 |
are filled in with details of the specified thread. |
|
1796 |
</description> |
|
1797 |
<origin>jvmdi</origin> |
|
1798 |
<capabilities> |
|
1799 |
</capabilities> |
|
1800 |
<parameters> |
|
1801 |
<param id="thread"> |
|
1802 |
<jthread null="current" impl="noconvert" started="maybe"/> |
|
1803 |
<description> |
|
1804 |
The thread to query. |
|
1805 |
</description> |
|
1806 |
</param> |
|
1807 |
<param id="info_ptr"> |
|
1808 |
<outptr><struct>jvmtiThreadInfo</struct></outptr> |
|
1809 |
<description> |
|
1810 |
On return, filled with information describing the specified thread. |
|
1811 |
<p/> |
|
1812 |
For JDK 1.1 implementations that don't |
|
1813 |
recognize context class loaders, |
|
1814 |
the <code>context_class_loader</code> field will be NULL. |
|
1815 |
</description> |
|
1816 |
</param> |
|
1817 |
</parameters> |
|
1818 |
<errors> |
|
1819 |
</errors> |
|
1820 |
</function> |
|
1821 |
||
1822 |
<function id="GetOwnedMonitorInfo" num="10"> |
|
1823 |
<synopsis>Get Owned Monitor Info</synopsis> |
|
1824 |
<description> |
|
1825 |
Get information about the monitors owned by the |
|
1826 |
specified thread. |
|
1827 |
</description> |
|
1828 |
<origin>jvmdiClone</origin> |
|
1829 |
<capabilities> |
|
1830 |
<required id="can_get_owned_monitor_info"></required> |
|
1831 |
</capabilities> |
|
1832 |
<parameters> |
|
1833 |
<param id="thread"> |
|
1834 |
<jthread null="current"/> |
|
1835 |
<description> |
|
1836 |
The thread to query. |
|
1837 |
</description> |
|
1838 |
</param> |
|
1839 |
<param id="owned_monitor_count_ptr"> |
|
1840 |
<outptr><jint/></outptr> |
|
1841 |
<description> |
|
1842 |
The number of monitors returned. |
|
1843 |
</description> |
|
1844 |
</param> |
|
1845 |
<param id="owned_monitors_ptr"> |
|
1846 |
<allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf> |
|
1847 |
<description> |
|
1848 |
The array of owned monitors. |
|
1849 |
</description> |
|
1850 |
</param> |
|
1851 |
</parameters> |
|
1852 |
<errors> |
|
1853 |
</errors> |
|
1854 |
</function> |
|
1855 |
||
1856 |
<function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1"> |
|
1857 |
<synopsis>Get Owned Monitor Stack Depth Info</synopsis> |
|
1858 |
<typedef id="jvmtiMonitorStackDepthInfo" |
|
1859 |
label="Monitor stack depth information structure"> |
|
1860 |
<field id="monitor"> |
|
1861 |
<jobject/> |
|
1862 |
<description> |
|
1863 |
The owned monitor. |
|
1864 |
</description> |
|
1865 |
</field> |
|
1866 |
<field id="stack_depth"> |
|
1867 |
<jint/> |
|
1868 |
<description> |
|
1869 |
The stack depth. Corresponds to the stack depth used in the |
|
1870 |
<internallink id="stack">Stack Frame functions</internallink>. |
|
1871 |
That is, zero is the current frame, one is the frame which |
|
1872 |
called the current frame. And it is negative one if the |
|
1873 |
implementation cannot determine the stack depth (e.g., for |
|
1874 |
monitors acquired by JNI <code>MonitorEnter</code>). |
|
1875 |
</description> |
|
1876 |
</field> |
|
1877 |
</typedef> |
|
1878 |
<description> |
|
1879 |
Get information about the monitors owned by the |
|
1880 |
specified thread and the depth of the stack frame which locked them. |
|
1881 |
</description> |
|
1882 |
<origin>new</origin> |
|
1883 |
<capabilities> |
|
1884 |
<required id="can_get_owned_monitor_stack_depth_info"></required> |
|
1885 |
</capabilities> |
|
1886 |
<parameters> |
|
1887 |
<param id="thread"> |
|
1888 |
<jthread null="current"/> |
|
1889 |
<description> |
|
1890 |
The thread to query. |
|
1891 |
</description> |
|
1892 |
</param> |
|
1893 |
<param id="monitor_info_count_ptr"> |
|
1894 |
<outptr><jint/></outptr> |
|
1895 |
<description> |
|
1896 |
The number of monitors returned. |
|
1897 |
</description> |
|
1898 |
</param> |
|
1899 |
<param id="monitor_info_ptr"> |
|
18081
c0a9e6c4058c
6493116: JVMTI Doc: GetOwnedMonitorStackDepthInfo has a typo in monitor_info_ptr parameter description
sspitsyn
parents:
14571
diff
changeset
|
1900 |
<allocbuf outcount="monitor_info_count_ptr"> |
1 | 1901 |
<struct>jvmtiMonitorStackDepthInfo</struct> |
1902 |
</allocbuf> |
|
1903 |
<description> |
|
1904 |
The array of owned monitor depth information. |
|
1905 |
</description> |
|
1906 |
</param> |
|
1907 |
</parameters> |
|
1908 |
<errors> |
|
1909 |
</errors> |
|
1910 |
</function> |
|
1911 |
||
1912 |
<function id="GetCurrentContendedMonitor" num="11"> |
|
1913 |
<synopsis>Get Current Contended Monitor</synopsis> |
|
1914 |
<description> |
|
1915 |
Get the object, if any, whose monitor the specified thread is waiting to |
|
1916 |
enter or waiting to regain through <code>java.lang.Object.wait</code>. |
|
1917 |
</description> |
|
1918 |
<origin>jvmdi</origin> |
|
1919 |
<capabilities> |
|
1920 |
<required id="can_get_current_contended_monitor"></required> |
|
1921 |
</capabilities> |
|
1922 |
<parameters> |
|
1923 |
<param id="thread"> |
|
1924 |
<jthread null="current"/> |
|
1925 |
<description> |
|
1926 |
The thread to query. |
|
1927 |
</description> |
|
1928 |
</param> |
|
1929 |
<param id="monitor_ptr"> |
|
1930 |
<outptr><jobject/></outptr> |
|
1931 |
<description> |
|
1932 |
On return, filled with the current contended monitor, or |
|
1933 |
NULL if there is none. |
|
1934 |
</description> |
|
1935 |
</param> |
|
1936 |
</parameters> |
|
1937 |
<errors> |
|
1938 |
</errors> |
|
1939 |
</function> |
|
1940 |
||
1941 |
<callback id="jvmtiStartFunction"> |
|
1942 |
<void/> |
|
1943 |
<synopsis>Agent Start Function</synopsis> |
|
1944 |
<description> |
|
1945 |
Agent supplied callback function. |
|
1946 |
This function is the entry point for an agent thread |
|
1947 |
started with |
|
1948 |
<functionlink id="RunAgentThread"></functionlink>. |
|
1949 |
</description> |
|
1950 |
<parameters> |
|
1951 |
<param id="jvmti_env"> |
|
1952 |
<outptr> |
|
1953 |
<struct>jvmtiEnv</struct> |
|
1954 |
</outptr> |
|
1955 |
<description> |
|
1956 |
The <jvmti/> environment. |
|
1957 |
</description> |
|
1958 |
</param> |
|
1959 |
<param id="jni_env"> |
|
1960 |
<outptr> |
|
1961 |
<struct>JNIEnv</struct> |
|
1962 |
</outptr> |
|
1963 |
<description> |
|
1964 |
The JNI environment. |
|
1965 |
</description> |
|
1966 |
</param> |
|
1967 |
<param id="arg"> |
|
1968 |
<outptr> |
|
1969 |
<void/> |
|
1970 |
</outptr> |
|
1971 |
<description> |
|
1972 |
The <code>arg</code> parameter passed to |
|
1973 |
<functionlink id="RunAgentThread"></functionlink>. |
|
1974 |
</description> |
|
1975 |
</param> |
|
1976 |
</parameters> |
|
1977 |
</callback> |
|
1978 |
||
1979 |
<function id="RunAgentThread" num="12"> |
|
1980 |
<synopsis>Run Agent Thread</synopsis> |
|
1981 |
<description> |
|
1982 |
Starts the execution of an agent thread. with the specified native function. |
|
1983 |
The parameter <paramlink id="arg"></paramlink> is forwarded on to the |
|
1984 |
<functionlink id="jvmtiStartFunction">start function</functionlink> |
|
1985 |
(specified with <paramlink id="proc"></paramlink>) as its single argument. |
|
1986 |
This function allows the creation of agent threads |
|
1987 |
for handling communication with another process or for handling events |
|
1988 |
without the need to load a special subclass of <code>java.lang.Thread</code> or |
|
1989 |
implementer of <code>java.lang.Runnable</code>. |
|
1990 |
Instead, the created thread can run entirely in native code. |
|
1991 |
However, the created thread does require a newly created instance |
|
1992 |
of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to |
|
1993 |
which it will be associated. |
|
1994 |
The thread object can be created with JNI calls. |
|
1995 |
<p/> |
|
1996 |
The following common thread priorities are provided for your convenience: |
|
1997 |
<constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const"> |
|
1998 |
<constant id="JVMTI_THREAD_MIN_PRIORITY" num="1"> |
|
1999 |
Minimum possible thread priority |
|
2000 |
</constant> |
|
2001 |
<constant id="JVMTI_THREAD_NORM_PRIORITY" num="5"> |
|
2002 |
Normal thread priority |
|
2003 |
</constant> |
|
2004 |
<constant id="JVMTI_THREAD_MAX_PRIORITY" num="10"> |
|
2005 |
Maximum possible thread priority |
|
2006 |
</constant> |
|
2007 |
</constants> |
|
2008 |
<p/> |
|
2009 |
The new thread is started as a daemon thread with the specified |
|
2010 |
<paramlink id="priority"></paramlink>. |
|
2011 |
If enabled, a <eventlink id="ThreadStart"/> event will be sent. |
|
2012 |
<p/> |
|
2013 |
Since the thread has been started, the thread will be live when this function |
|
2014 |
returns, unless the thread has died immediately. |
|
2015 |
<p/> |
|
2016 |
The thread group of the thread is ignored -- specifically, the thread is not |
|
2017 |
added to the thread group and the thread is not seen on queries of the thread |
|
2018 |
group at either the Java programming language or <jvmti/> levels. |
|
2019 |
<p/> |
|
2020 |
The thread is not visible to Java programming language queries but is |
|
2021 |
included in <jvmti/> queries (for example, |
|
2022 |
<functionlink id="GetAllThreads"/> and |
|
2023 |
<functionlink id="GetAllStackTraces"/>). |
|
2024 |
<p/> |
|
2025 |
Upon execution of <code>proc</code>, the new thread will be attached to the |
|
2026 |
VM--see the JNI documentation on |
|
14287 | 2027 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060" |
1 | 2028 |
>Attaching to the VM</externallink>. |
2029 |
</description> |
|
2030 |
<origin>jvmdiClone</origin> |
|
2031 |
<capabilities> |
|
2032 |
</capabilities> |
|
2033 |
<parameters> |
|
2034 |
<param id="thread"> |
|
2035 |
<jthread impl="noconvert" started="no"/> |
|
2036 |
<description> |
|
2037 |
The thread to run. |
|
2038 |
</description> |
|
2039 |
</param> |
|
2040 |
<param id="proc"> |
|
2041 |
<ptrtype> |
|
2042 |
<struct>jvmtiStartFunction</struct> |
|
2043 |
</ptrtype> |
|
2044 |
<description> |
|
2045 |
The start function. |
|
2046 |
</description> |
|
2047 |
</param> |
|
2048 |
<param id="arg"> |
|
2049 |
<inbuf> |
|
2050 |
<void/> |
|
2051 |
<nullok><code>NULL</code> is passed to the start function</nullok> |
|
2052 |
</inbuf> |
|
2053 |
<description> |
|
2054 |
The argument to the start function. |
|
2055 |
</description> |
|
2056 |
</param> |
|
2057 |
<param id="priority"> |
|
2058 |
<jint/> |
|
2059 |
<description> |
|
2060 |
The priority of the started thread. Any thread |
|
2061 |
priority allowed by <code>java.lang.Thread.setPriority</code> can be used including |
|
2062 |
those in <datalink id="jvmtiThreadPriority"></datalink>. |
|
2063 |
</description> |
|
2064 |
</param> |
|
2065 |
</parameters> |
|
2066 |
<errors> |
|
2067 |
<error id="JVMTI_ERROR_INVALID_PRIORITY"> |
|
2068 |
<paramlink id="priority"/> is less than |
|
2069 |
<datalink id="JVMTI_THREAD_MIN_PRIORITY"/> |
|
2070 |
or greater than |
|
2071 |
<datalink id="JVMTI_THREAD_MAX_PRIORITY"/> |
|
2072 |
</error> |
|
2073 |
</errors> |
|
2074 |
</function> |
|
2075 |
||
2076 |
<function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103"> |
|
2077 |
<synopsis>Set Thread Local Storage</synopsis> |
|
2078 |
<description> |
|
2079 |
The VM stores a pointer value associated with each environment-thread |
|
2080 |
pair. This pointer value is called <i>thread-local storage</i>. |
|
2081 |
This value is <code>NULL</code> unless set with this function. |
|
2082 |
Agents can allocate memory in which they store thread specific |
|
2083 |
information. By setting thread-local storage it can then be |
|
2084 |
accessed with |
|
2085 |
<functionlink id="GetThreadLocalStorage"></functionlink>. |
|
2086 |
<p/> |
|
2087 |
This function is called by the agent to set the value of the <jvmti/> |
|
2088 |
thread-local storage. <jvmti/> supplies to the agent a pointer-size |
|
2089 |
thread-local storage that can be used to record per-thread |
|
2090 |
information. |
|
2091 |
</description> |
|
2092 |
<origin>jvmpi</origin> |
|
2093 |
<capabilities> |
|
2094 |
</capabilities> |
|
2095 |
<parameters> |
|
2096 |
<param id="thread"> |
|
2097 |
<jthread null="current"/> |
|
2098 |
<description> |
|
2099 |
Store to this thread. |
|
2100 |
</description> |
|
2101 |
</param> |
|
2102 |
<param id="data"> |
|
2103 |
<inbuf> |
|
2104 |
<void/> |
|
2105 |
<nullok>value is set to <code>NULL</code></nullok> |
|
2106 |
</inbuf> |
|
2107 |
<description> |
|
2108 |
The value to be entered into the thread-local storage. |
|
2109 |
</description> |
|
2110 |
</param> |
|
2111 |
</parameters> |
|
2112 |
<errors> |
|
2113 |
</errors> |
|
2114 |
</function> |
|
2115 |
||
2116 |
<function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102"> |
|
2117 |
<synopsis>Get Thread Local Storage</synopsis> |
|
2118 |
<description> |
|
2119 |
Called by the agent to get the value of the <jvmti/> thread-local |
|
2120 |
storage. |
|
2121 |
</description> |
|
2122 |
<origin>jvmpi</origin> |
|
2123 |
<capabilities> |
|
2124 |
</capabilities> |
|
2125 |
<parameters> |
|
2126 |
<param id="thread"> |
|
2127 |
<jthread null="current" impl="noconvert"/> |
|
2128 |
<description> |
|
2129 |
Retrieve from this thread. |
|
2130 |
</description> |
|
2131 |
</param> |
|
2132 |
<param id="data_ptr"> |
|
2133 |
<agentbuf><void/></agentbuf> |
|
2134 |
<description> |
|
2135 |
Pointer through which the value of the thread local |
|
2136 |
storage is returned. |
|
2137 |
If thread-local storage has not been set with |
|
2138 |
<functionlink id="SetThreadLocalStorage"></functionlink> the returned |
|
2139 |
pointer is <code>NULL</code>. |
|
2140 |
</description> |
|
2141 |
</param> |
|
2142 |
</parameters> |
|
2143 |
<errors> |
|
2144 |
</errors> |
|
2145 |
</function> |
|
2146 |
||
2147 |
</category> |
|
2148 |
||
2149 |
<category id="thread_groups" label="Thread Group"> |
|
2150 |
<intro> |
|
2151 |
</intro> |
|
2152 |
||
2153 |
<function id="GetTopThreadGroups" num="13"> |
|
2154 |
<synopsis>Get Top Thread Groups</synopsis> |
|
2155 |
<description> |
|
2156 |
Return all top-level (parentless) thread groups in the VM. |
|
2157 |
</description> |
|
2158 |
<origin>jvmdi</origin> |
|
2159 |
<capabilities> |
|
2160 |
</capabilities> |
|
2161 |
<parameters> |
|
2162 |
<param id="group_count_ptr"> |
|
2163 |
<outptr><jint/></outptr> |
|
2164 |
<description> |
|
2165 |
On return, points to the number of top-level thread groups. |
|
2166 |
</description> |
|
2167 |
</param> |
|
2168 |
<param id="groups_ptr"> |
|
2169 |
<allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> |
|
2170 |
<description> |
|
2171 |
On return, refers to a pointer to the top-level thread group array. |
|
2172 |
</description> |
|
2173 |
</param> |
|
2174 |
</parameters> |
|
2175 |
<errors> |
|
2176 |
</errors> |
|
2177 |
</function> |
|
2178 |
||
2179 |
<function id="GetThreadGroupInfo" num="14"> |
|
2180 |
<synopsis>Get Thread Group Info</synopsis> |
|
2181 |
<typedef id="jvmtiThreadGroupInfo" label="Thread group information structure"> |
|
2182 |
<field id="parent"> |
|
2183 |
<jthreadGroup/> |
|
2184 |
<description> |
|
2185 |
The parent thread group. |
|
2186 |
</description> |
|
2187 |
</field> |
|
2188 |
<field id="name"> |
|
2189 |
<allocfieldbuf><char/></allocfieldbuf> |
|
2190 |
<description> |
|
2191 |
The thread group's name, encoded as a |
|
2192 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
2193 |
</description> |
|
2194 |
</field> |
|
2195 |
<field id="max_priority"> |
|
2196 |
<jint/> |
|
2197 |
<description> |
|
2198 |
The maximum priority for this thread group. |
|
2199 |
</description> |
|
2200 |
</field> |
|
2201 |
<field id="is_daemon"> |
|
2202 |
<jboolean/> |
|
2203 |
<description> |
|
2204 |
Is this a daemon thread group? |
|
2205 |
</description> |
|
2206 |
</field> |
|
2207 |
</typedef> |
|
2208 |
<description> |
|
2209 |
Get information about the thread group. The fields of the |
|
2210 |
<functionlink id="jvmtiThreadGroupInfo"></functionlink> structure |
|
2211 |
are filled in with details of the specified thread group. |
|
2212 |
</description> |
|
2213 |
<origin>jvmdi</origin> |
|
2214 |
<capabilities> |
|
2215 |
</capabilities> |
|
2216 |
<parameters> |
|
2217 |
<param id="group"> |
|
2218 |
<jthreadGroup/> |
|
2219 |
<description> |
|
2220 |
The thread group to query. |
|
2221 |
</description> |
|
2222 |
</param> |
|
2223 |
<param id="info_ptr"> |
|
2224 |
<outptr><struct>jvmtiThreadGroupInfo</struct></outptr> |
|
2225 |
<description> |
|
2226 |
On return, filled with information describing the specified |
|
2227 |
thread group. |
|
2228 |
</description> |
|
2229 |
</param> |
|
2230 |
</parameters> |
|
2231 |
<errors> |
|
2232 |
</errors> |
|
2233 |
</function> |
|
2234 |
||
2235 |
<function id="GetThreadGroupChildren" num="15"> |
|
2236 |
<synopsis>Get Thread Group Children</synopsis> |
|
2237 |
<description> |
|
2238 |
Get the live threads and active subgroups in this thread group. |
|
2239 |
</description> |
|
2240 |
<origin>jvmdi</origin> |
|
2241 |
<capabilities> |
|
2242 |
</capabilities> |
|
2243 |
<parameters> |
|
2244 |
<param id="group"> |
|
2245 |
<jthreadGroup/> |
|
2246 |
<description> |
|
2247 |
The group to query. |
|
2248 |
</description> |
|
2249 |
</param> |
|
2250 |
<param id="thread_count_ptr"> |
|
2251 |
<outptr><jint/></outptr> |
|
2252 |
<description> |
|
2253 |
On return, points to the number of live threads in this thread group. |
|
2254 |
</description> |
|
2255 |
</param> |
|
2256 |
<param id="threads_ptr"> |
|
2257 |
<allocbuf outcount="thread_count_ptr"><jthread/></allocbuf> |
|
2258 |
<description> |
|
2259 |
On return, points to an array of the live threads in this thread group. |
|
2260 |
</description> |
|
2261 |
</param> |
|
2262 |
<param id="group_count_ptr"> |
|
2263 |
<outptr><jint/></outptr> |
|
2264 |
<description> |
|
2265 |
On return, points to the number of active child thread groups |
|
2266 |
</description> |
|
2267 |
</param> |
|
2268 |
<param id="groups_ptr"> |
|
2269 |
<allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf> |
|
2270 |
<description> |
|
2271 |
On return, points to an array of the active child thread groups. |
|
2272 |
</description> |
|
2273 |
</param> |
|
2274 |
</parameters> |
|
2275 |
<errors> |
|
2276 |
</errors> |
|
2277 |
</function> |
|
2278 |
</category> |
|
2279 |
||
2280 |
<category id="stack" label="Stack Frame"> |
|
2281 |
<intro> |
|
2282 |
These functions provide information about the stack of a thread. |
|
2283 |
Stack frames are referenced by depth. |
|
2284 |
The frame at depth zero is the current frame. |
|
2285 |
<p/> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
2286 |
Stack frames are as described in |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
2287 |
<vmspec chapter="3.6"/>, |
1 | 2288 |
That is, they correspond to method |
2289 |
invocations (including native methods) but do not correspond to platform native or |
|
2290 |
VM internal frames. |
|
2291 |
<p/> |
|
2292 |
A <jvmti/> implementation may use method invocations to launch a thread and |
|
2293 |
the corresponding frames may be included in the stack as presented by these functions -- |
|
2294 |
that is, there may be frames shown |
|
2295 |
deeper than <code>main()</code> and <code>run()</code>. |
|
2296 |
However this presentation must be consistent across all <jvmti/> functionality which |
|
2297 |
uses stack frames or stack depth. |
|
2298 |
</intro> |
|
2299 |
||
2300 |
<typedef id="jvmtiFrameInfo" label="Stack frame information structure"> |
|
2301 |
<description> |
|
2302 |
Information about a stack frame is returned in this structure. |
|
2303 |
</description> |
|
2304 |
<field id="method"> |
|
2305 |
<jmethodID/> |
|
2306 |
<description> |
|
2307 |
The method executing in this frame. |
|
2308 |
</description> |
|
2309 |
</field> |
|
2310 |
<field id="location"> |
|
2311 |
<jlocation/> |
|
2312 |
<description> |
|
2313 |
The index of the instruction executing in this frame. |
|
2314 |
<code>-1</code> if the frame is executing a native method. |
|
2315 |
</description> |
|
2316 |
</field> |
|
2317 |
</typedef> |
|
2318 |
||
2319 |
<typedef id="jvmtiStackInfo" label="Stack information structure"> |
|
2320 |
<description> |
|
2321 |
Information about a set of stack frames is returned in this structure. |
|
2322 |
</description> |
|
2323 |
<field id="thread"> |
|
2324 |
<jthread/> |
|
2325 |
<description> |
|
2326 |
On return, the thread traced. |
|
2327 |
</description> |
|
2328 |
</field> |
|
2329 |
<field id="state"> |
|
2330 |
<jint/> |
|
2331 |
<description> |
|
2332 |
On return, the thread state. See <functionlink id="GetThreadState"></functionlink>. |
|
2333 |
</description> |
|
2334 |
</field> |
|
2335 |
<field id="frame_buffer"> |
|
2336 |
<outbuf incount="max_frame_count"> |
|
2337 |
<struct>jvmtiFrameInfo</struct> |
|
2338 |
</outbuf> |
|
2339 |
<description> |
|
2340 |
On return, this agent allocated buffer is filled |
|
2341 |
with stack frame information. |
|
2342 |
</description> |
|
2343 |
</field> |
|
2344 |
<field id="frame_count"> |
|
2345 |
<jint/> |
|
2346 |
<description> |
|
2347 |
On return, the number of records filled into |
|
2348 |
<code>frame_buffer</code>. |
|
2349 |
This will be |
|
2350 |
min(<code>max_frame_count</code>, <i>stackDepth</i>). |
|
2351 |
</description> |
|
2352 |
</field> |
|
2353 |
</typedef> |
|
2354 |
||
2355 |
<function id="GetStackTrace" num="104"> |
|
2356 |
<synopsis>Get Stack Trace</synopsis> |
|
2357 |
<description> |
|
2358 |
Get information about the stack of a thread. |
|
2359 |
If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack, |
|
2360 |
the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, |
|
2361 |
otherwise the entire stack is returned. |
|
2362 |
The topmost frames, those most recently invoked, are at the beginning of the returned buffer. |
|
2363 |
<p/> |
|
2364 |
The following example causes up to five of the topmost frames |
|
2365 |
to be returned and (if there are any frames) the currently |
|
2366 |
executing method name to be printed. |
|
2367 |
<example> |
|
2368 |
jvmtiFrameInfo frames[5]; |
|
2369 |
jint count; |
|
2370 |
jvmtiError err; |
|
2371 |
||
2372 |
err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, |
|
14571
1e4d36113875
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
14287
diff
changeset
|
2373 |
frames, &count); |
1 | 2374 |
if (err == JVMTI_ERROR_NONE && count >= 1) { |
2375 |
char *methodName; |
|
2376 |
err = (*jvmti)->GetMethodName(jvmti, frames[0].method, |
|
14571
1e4d36113875
8003690: Example code in JVMTI GetStackTrace documentation is broken
mikael
parents:
14287
diff
changeset
|
2377 |
&methodName, NULL, NULL); |
1 | 2378 |
if (err == JVMTI_ERROR_NONE) { |
2379 |
printf("Executing method: %s", methodName); |
|
2380 |
} |
|
2381 |
} |
|
2382 |
</example> |
|
2383 |
<todo> |
|
2384 |
check example code. |
|
2385 |
</todo> |
|
2386 |
<p/> |
|
2387 |
The <paramlink id="thread"></paramlink> need not be suspended |
|
2388 |
to call this function. |
|
2389 |
<p/> |
|
2390 |
The <functionlink id="GetLineNumberTable"></functionlink> |
|
2391 |
function can be used to map locations to line numbers. Note that |
|
2392 |
this mapping can be done lazily. |
|
2393 |
</description> |
|
2394 |
<origin>jvmpi</origin> |
|
2395 |
<capabilities> |
|
2396 |
</capabilities> |
|
2397 |
<parameters> |
|
2398 |
<param id="thread"> |
|
2399 |
<jthread null="current"/> |
|
2400 |
<description> |
|
2401 |
Fetch the stack trace of this thread. |
|
2402 |
</description> |
|
2403 |
</param> |
|
2404 |
<param id="start_depth"> |
|
2405 |
<jint/> |
|
2406 |
<description> |
|
2407 |
Begin retrieving frames at this depth. |
|
2408 |
If non-negative, count from the current frame, |
|
2409 |
the first frame retrieved is at depth <code>start_depth</code>. |
|
2410 |
For example, if zero, start from the current frame; if one, start from the |
|
2411 |
caller of the current frame; if two, start from the caller of the |
|
2412 |
caller of the current frame; and so on. |
|
2413 |
If negative, count from below the oldest frame, |
|
2414 |
the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>, |
|
2415 |
where <i>stackDepth</i> is the count of frames on the stack. |
|
2416 |
For example, if negative one, only the oldest frame is retrieved; |
|
2417 |
if negative two, start from the frame called by the oldest frame. |
|
2418 |
</description> |
|
2419 |
</param> |
|
2420 |
<param id="max_frame_count"> |
|
2421 |
<jint min="0"/> |
|
2422 |
<description> |
|
2423 |
The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. |
|
2424 |
</description> |
|
2425 |
</param> |
|
2426 |
<param id="frame_buffer"> |
|
2427 |
<outbuf incount="max_frame_count" outcount="count_ptr"> |
|
2428 |
<struct>jvmtiFrameInfo</struct> |
|
2429 |
</outbuf> |
|
2430 |
<description> |
|
2431 |
On return, this agent allocated buffer is filled |
|
2432 |
with stack frame information. |
|
2433 |
</description> |
|
2434 |
</param> |
|
2435 |
<param id="count_ptr"> |
|
2436 |
<outptr><jint/></outptr> |
|
2437 |
<description> |
|
2438 |
On return, points to the number of records filled in. |
|
2439 |
For non-negative <code>start_depth</code>, this will be |
|
2440 |
min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>). |
|
2441 |
For negative <code>start_depth</code>, this will be |
|
2442 |
min(<code>max_frame_count</code>, <code>-start_depth</code>). |
|
2443 |
</description> |
|
2444 |
</param> |
|
2445 |
</parameters> |
|
2446 |
<errors> |
|
2447 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
2448 |
<paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>. |
|
2449 |
Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>. |
|
2450 |
</error> |
|
2451 |
</errors> |
|
2452 |
</function> |
|
2453 |
||
2454 |
||
2455 |
<function id="GetAllStackTraces" num="100"> |
|
2456 |
<synopsis>Get All Stack Traces</synopsis> |
|
2457 |
<description> |
|
2458 |
Get information about the stacks of all live threads |
|
2459 |
(including <internallink id="RunAgentThread">agent threads</internallink>). |
|
2460 |
If <paramlink id="max_frame_count"/> is less than the depth of a stack, |
|
2461 |
the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, |
|
2462 |
otherwise the entire stack is returned. |
|
2463 |
The topmost frames, those most recently invoked, are at the beginning of the returned buffer. |
|
2464 |
<p/> |
|
2465 |
All stacks are collected simultaneously, that is, no changes will occur to the |
|
2466 |
thread state or stacks between the sampling of one thread and the next. |
|
2467 |
The threads need not be suspended. |
|
2468 |
||
2469 |
<example> |
|
2470 |
jvmtiStackInfo *stack_info; |
|
2471 |
jint thread_count; |
|
2472 |
int ti; |
|
2473 |
jvmtiError err; |
|
2474 |
||
2475 |
err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); |
|
2476 |
if (err != JVMTI_ERROR_NONE) { |
|
2477 |
... |
|
2478 |
} |
|
2479 |
for (ti = 0; ti < thread_count; ++ti) { |
|
2480 |
jvmtiStackInfo *infop = &stack_info[ti]; |
|
2481 |
jthread thread = infop->thread; |
|
2482 |
jint state = infop->state; |
|
2483 |
jvmtiFrameInfo *frames = infop->frame_buffer; |
|
2484 |
int fi; |
|
2485 |
||
2486 |
myThreadAndStatePrinter(thread, state); |
|
2487 |
for (fi = 0; fi < infop->frame_count; fi++) { |
|
2488 |
myFramePrinter(frames[fi].method, frames[fi].location); |
|
2489 |
} |
|
2490 |
} |
|
2491 |
/* this one Deallocate call frees all data allocated by GetAllStackTraces */ |
|
2492 |
err = (*jvmti)->Deallocate(jvmti, stack_info); |
|
2493 |
</example> |
|
2494 |
<todo> |
|
2495 |
check example code. |
|
2496 |
</todo> |
|
2497 |
||
2498 |
</description> |
|
2499 |
<origin>new</origin> |
|
2500 |
<capabilities> |
|
2501 |
</capabilities> |
|
2502 |
<parameters> |
|
2503 |
<param id="max_frame_count"> |
|
2504 |
<jint min="0"/> |
|
2505 |
<description> |
|
2506 |
The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. |
|
2507 |
</description> |
|
2508 |
</param> |
|
2509 |
<param id="stack_info_ptr"> |
|
2510 |
<allocbuf> |
|
2511 |
<struct>jvmtiStackInfo</struct> |
|
2512 |
</allocbuf> |
|
2513 |
<description> |
|
2514 |
On return, this buffer is filled |
|
2515 |
with stack information for each thread. |
|
2516 |
The number of <datalink id="jvmtiStackInfo"/> records is determined |
|
2517 |
by <paramlink id="thread_count_ptr"/>. |
|
2518 |
<p/> |
|
2519 |
Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> |
|
2520 |
buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. |
|
2521 |
These buffers must not be separately deallocated. |
|
2522 |
</description> |
|
2523 |
</param> |
|
2524 |
<param id="thread_count_ptr"> |
|
2525 |
<outptr><jint/></outptr> |
|
2526 |
<description> |
|
2527 |
The number of threads traced. |
|
2528 |
</description> |
|
2529 |
</param> |
|
2530 |
</parameters> |
|
2531 |
<errors> |
|
2532 |
</errors> |
|
2533 |
</function> |
|
2534 |
||
2535 |
<function id="GetThreadListStackTraces" num="101"> |
|
2536 |
<synopsis>Get Thread List Stack Traces</synopsis> |
|
2537 |
<description> |
|
2538 |
Get information about the stacks of the supplied threads. |
|
2539 |
If <paramlink id="max_frame_count"/> is less than the depth of a stack, |
|
2540 |
the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, |
|
2541 |
otherwise the entire stack is returned. |
|
2542 |
The topmost frames, those most recently invoked, are at the beginning of the returned buffer. |
|
2543 |
<p/> |
|
2544 |
All stacks are collected simultaneously, that is, no changes will occur to the |
|
2545 |
thread state or stacks between the sampling one thread and the next. |
|
2546 |
The threads need not be suspended. |
|
2547 |
<p/> |
|
2548 |
If a thread has not yet started or terminates before the stack information is collected, |
|
2549 |
a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero) |
|
2550 |
will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked. |
|
2551 |
<p/> |
|
2552 |
See the example for the similar function |
|
2553 |
<functionlink id="GetAllStackTraces"/>. |
|
2554 |
</description> |
|
2555 |
<origin>new</origin> |
|
2556 |
<capabilities> |
|
2557 |
</capabilities> |
|
2558 |
<parameters> |
|
2559 |
<param id="thread_count"> |
|
2560 |
<jint min="0"/> |
|
2561 |
<description> |
|
2562 |
The number of threads to trace. |
|
2563 |
</description> |
|
2564 |
</param> |
|
2565 |
<param id="thread_list"> |
|
2566 |
<inbuf incount="thread_count"><jthread/></inbuf> |
|
2567 |
<description> |
|
2568 |
The list of threads to trace. |
|
2569 |
</description> |
|
2570 |
</param> |
|
2571 |
<param id="max_frame_count"> |
|
2572 |
<jint min="0"/> |
|
2573 |
<description> |
|
2574 |
The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread. |
|
2575 |
</description> |
|
2576 |
</param> |
|
2577 |
<param id="stack_info_ptr"> |
|
2578 |
<allocbuf outcount="thread_count"> |
|
2579 |
<struct>jvmtiStackInfo</struct> |
|
2580 |
</allocbuf> |
|
2581 |
<description> |
|
2582 |
On return, this buffer is filled |
|
2583 |
with stack information for each thread. |
|
2584 |
The number of <datalink id="jvmtiStackInfo"/> records is determined |
|
2585 |
by <paramlink id="thread_count"/>. |
|
2586 |
<p/> |
|
2587 |
Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> |
|
2588 |
buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>. |
|
2589 |
These buffers must not be separately deallocated. |
|
2590 |
</description> |
|
2591 |
</param> |
|
2592 |
</parameters> |
|
2593 |
<errors> |
|
2594 |
<error id="JVMTI_ERROR_INVALID_THREAD"> |
|
2595 |
An element in <paramlink id="thread_list"/> is not a thread object. |
|
2596 |
</error> |
|
2597 |
</errors> |
|
2598 |
</function> |
|
2599 |
||
2600 |
<elide> |
|
2601 |
<function id="AsyncGetStackTrace" num="1000"> |
|
2602 |
<synopsis>Get Stack Trace--Asynchronous</synopsis> |
|
2603 |
<description> |
|
2604 |
Get information about the entire stack of a thread (or a sub-section of it). |
|
2605 |
This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink> |
|
2606 |
and is reentrant and safe to call |
|
2607 |
from asynchronous signal handlers. |
|
2608 |
The stack trace is returned only for the calling thread. |
|
2609 |
<p/> |
|
2610 |
The <functionlink id="GetLineNumberTable"></functionlink> |
|
2611 |
function can be used to map locations to line numbers. Note that |
|
2612 |
this mapping can be done lazily. |
|
2613 |
</description> |
|
2614 |
<origin>jvmpi</origin> |
|
2615 |
<capabilities> |
|
2616 |
<required id="can_get_async_stack_trace"></required> |
|
2617 |
<capability id="can_show_JVM_spec_async_frames"> |
|
2618 |
If <code>false</code>, |
|
2619 |
<paramlink id="use_java_stack"></paramlink> |
|
2620 |
must be <code>false</code>. |
|
2621 |
</capability> |
|
2622 |
</capabilities> |
|
2623 |
<parameters> |
|
2624 |
<param id="use_java_stack"> |
|
2625 |
<jboolean/> |
|
2626 |
<description> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
2627 |
Return the stack showing <vmspec/> |
1 | 2628 |
model of the stack; |
2629 |
otherwise, show the internal representation of the stack with |
|
2630 |
inlined and optimized methods missing. If the virtual machine |
|
2631 |
is using the <i>Java Virtual Machine Specification</i> stack model |
|
2632 |
internally, this flag is ignored. |
|
2633 |
</description> |
|
2634 |
</param> |
|
2635 |
<param id="max_count"> |
|
2636 |
<jint min="0"/> |
|
2637 |
<description> |
|
2638 |
The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve. |
|
2639 |
Retrieve this many unless the stack depth is less than <code>max_count</code>. |
|
2640 |
</description> |
|
2641 |
</param> |
|
2642 |
<param id="frame_buffer"> |
|
2643 |
<outbuf incount="max_count" outcount="count_ptr"> |
|
2644 |
<struct>jvmtiFrameInfo</struct> |
|
2645 |
<nullok>this information is not returned</nullok> |
|
2646 |
</outbuf> |
|
2647 |
<description> |
|
2648 |
The agent passes in a buffer |
|
2649 |
large enough to hold <code>max_count</code> records of |
|
2650 |
<datalink id="jvmtiFrameInfo"></datalink>. This buffer must be |
|
2651 |
pre-allocated by the agent. |
|
2652 |
</description> |
|
2653 |
</param> |
|
2654 |
<param id="count_ptr"> |
|
2655 |
<outptr><jint/></outptr> |
|
2656 |
<description> |
|
2657 |
On return, points to the number of records filled in.. |
|
2658 |
</description> |
|
2659 |
</param> |
|
2660 |
</parameters> |
|
2661 |
<errors> |
|
2662 |
<error id="JVMTI_ERROR_UNATTACHED_THREAD"> |
|
2663 |
The thread being used to call this function is not attached |
|
2664 |
to the virtual machine. Calls must be made from attached threads. |
|
2665 |
</error> |
|
2666 |
</errors> |
|
2667 |
</function> |
|
2668 |
</elide> |
|
2669 |
||
2670 |
<function id="GetFrameCount" num="16"> |
|
2671 |
<synopsis>Get Frame Count</synopsis> |
|
2672 |
<description> |
|
2673 |
Get the number of frames currently in the specified thread's call stack. |
|
2674 |
<p/> |
|
2675 |
If this function is called for a thread actively executing bytecodes (for example, |
|
2676 |
not the current thread and not suspended), the information returned is transient. |
|
2677 |
</description> |
|
2678 |
<origin>jvmdi</origin> |
|
2679 |
<capabilities> |
|
2680 |
</capabilities> |
|
2681 |
<parameters> |
|
2682 |
<param id="thread"> |
|
2683 |
<jthread null="current"/> |
|
2684 |
<description> |
|
2685 |
The thread to query. |
|
2686 |
</description> |
|
2687 |
</param> |
|
2688 |
<param id="count_ptr"> |
|
2689 |
<outptr><jint/></outptr> |
|
2690 |
<description> |
|
2691 |
On return, points to the number of frames in the call stack. |
|
2692 |
</description> |
|
2693 |
</param> |
|
2694 |
</parameters> |
|
2695 |
<errors> |
|
2696 |
</errors> |
|
2697 |
</function> |
|
2698 |
||
2699 |
<function id="PopFrame" num="80"> |
|
2700 |
<synopsis>Pop Frame</synopsis> |
|
2701 |
<description> |
|
2702 |
Pop the current frame of <code>thread</code>'s stack. |
|
2703 |
Popping a frame takes you to the previous frame. |
|
2704 |
When the thread is resumed, the execution |
|
2705 |
state of the thread is reset to the state |
|
2706 |
immediately before the called method was invoked. |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
2707 |
That is (using <vmspec/> terminology): |
1 | 2708 |
<ul> |
2709 |
<li>the current frame is discarded as the previous frame becomes the current one</li> |
|
2710 |
<li>the operand stack is restored--the argument values are added back |
|
2711 |
and if the invoke was not <code>invokestatic</code>, |
|
2712 |
<code>objectref</code> is added back as well</li> |
|
2713 |
<li>the Java virtual machine PC is restored to the opcode |
|
2714 |
of the invoke instruction</li> |
|
2715 |
</ul> |
|
2716 |
Note however, that any changes to the arguments, which |
|
2717 |
occurred in the called method, remain; |
|
2718 |
when execution continues, the first instruction to |
|
2719 |
execute will be the invoke. |
|
2720 |
<p/> |
|
2721 |
Between calling <code>PopFrame</code> and resuming the |
|
2722 |
thread the state of the stack is undefined. |
|
2723 |
To pop frames beyond the first, |
|
2724 |
these three steps must be repeated: |
|
2725 |
<ul> |
|
2726 |
<li>suspend the thread via an event (step, breakpoint, ...)</li> |
|
2727 |
<li>call <code>PopFrame</code></li> |
|
2728 |
<li>resume the thread</li> |
|
2729 |
</ul> |
|
2730 |
<p/> |
|
2731 |
A lock acquired by calling the called method |
|
2732 |
(if it is a <code>synchronized</code> method) |
|
2733 |
and locks acquired by entering <code>synchronized</code> |
|
2734 |
blocks within the called method are released. |
|
2735 |
Note: this does not apply to native locks or |
|
2736 |
<code>java.util.concurrent.locks</code> locks. |
|
2737 |
<p/> |
|
2738 |
Finally blocks are not executed. |
|
2739 |
<p/> |
|
2740 |
Changes to global state are not addressed and thus remain changed. |
|
2741 |
<p/> |
|
2742 |
The specified thread must be suspended (which implies it cannot be the current thread). |
|
2743 |
<p/> |
|
2744 |
Both the called method and calling method must be non-native Java programming |
|
2745 |
language methods. |
|
2746 |
<p/> |
|
2747 |
No <jvmti/> events are generated by this function. |
|
2748 |
</description> |
|
2749 |
<origin>jvmdi</origin> |
|
2750 |
<capabilities> |
|
2751 |
<required id="can_pop_frame"></required> |
|
2752 |
</capabilities> |
|
2753 |
<parameters> |
|
2754 |
<param id="thread"> |
|
2755 |
<jthread/> |
|
2756 |
<description> |
|
2757 |
The thread whose current frame is to be popped. |
|
2758 |
</description> |
|
2759 |
</param> |
|
2760 |
</parameters> |
|
2761 |
<errors> |
|
2762 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
2763 |
Called or calling method is a native method. |
|
2764 |
The implementation is unable to pop this frame. |
|
2765 |
</error> |
|
2766 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
2767 |
Thread was not suspended. |
|
2768 |
</error> |
|
2769 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
2770 |
There are less than two stack frames on the call stack. |
|
2771 |
</error> |
|
2772 |
</errors> |
|
2773 |
</function> |
|
2774 |
||
2775 |
<function id="GetFrameLocation" num="19"> |
|
2776 |
<synopsis>Get Frame Location</synopsis> |
|
2777 |
<description> |
|
2778 |
<p/> |
|
2779 |
For a Java programming language frame, return the location of the instruction |
|
2780 |
currently executing. |
|
2781 |
</description> |
|
2782 |
<origin>jvmdiClone</origin> |
|
2783 |
<capabilities> |
|
2784 |
</capabilities> |
|
2785 |
<parameters> |
|
2786 |
<param id="thread"> |
|
2787 |
<jthread null="current" frame="frame"/> |
|
2788 |
<description> |
|
2789 |
The thread of the frame to query. |
|
2790 |
</description> |
|
2791 |
</param> |
|
2792 |
<param id="depth"> |
|
2793 |
<jframeID thread="thread"/> |
|
2794 |
<description> |
|
2795 |
The depth of the frame to query. |
|
2796 |
</description> |
|
2797 |
</param> |
|
2798 |
<param id="method_ptr"> |
|
2799 |
<outptr><jmethodID/></outptr> |
|
2800 |
<description> |
|
2801 |
On return, points to the method for the current location. |
|
2802 |
</description> |
|
2803 |
</param> |
|
2804 |
<param id="location_ptr"> |
|
2805 |
<outptr><jlocation/></outptr> |
|
2806 |
<description> |
|
2807 |
On return, points to the index of the currently |
|
2808 |
executing instruction. |
|
2809 |
Is set to <code>-1</code> if the frame is executing |
|
2810 |
a native method. |
|
2811 |
</description> |
|
2812 |
</param> |
|
2813 |
</parameters> |
|
2814 |
<errors> |
|
2815 |
</errors> |
|
2816 |
</function> |
|
2817 |
||
2818 |
<function id="NotifyFramePop" num="20"> |
|
2819 |
<synopsis>Notify Frame Pop</synopsis> |
|
2820 |
<description> |
|
2821 |
When the frame that is currently at <paramlink id="depth"></paramlink> |
|
2822 |
is popped from the stack, generate a |
|
2823 |
<eventlink id="FramePop"></eventlink> event. See the |
|
2824 |
<eventlink id="FramePop"></eventlink> event for details. |
|
2825 |
Only frames corresponding to non-native Java programming language |
|
2826 |
methods can receive notification. |
|
2827 |
<p/> |
|
2828 |
The specified thread must either be the current thread |
|
2829 |
or the thread must be suspended. |
|
2830 |
</description> |
|
2831 |
<origin>jvmdi</origin> |
|
2832 |
<capabilities> |
|
2833 |
<required id="can_generate_frame_pop_events"></required> |
|
2834 |
</capabilities> |
|
2835 |
<parameters> |
|
2836 |
<param id="thread"> |
|
2837 |
<jthread null="current" frame="depth"/> |
|
2838 |
<description> |
|
2839 |
The thread of the frame for which the frame pop event will be generated. |
|
2840 |
</description> |
|
2841 |
</param> |
|
2842 |
<param id="depth"> |
|
2843 |
<jframeID thread="thread"/> |
|
2844 |
<description> |
|
2845 |
The depth of the frame for which the frame pop event will be generated. |
|
2846 |
</description> |
|
2847 |
</param> |
|
2848 |
</parameters> |
|
2849 |
<errors> |
|
2850 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
2851 |
The frame at <code>depth</code> is executing a |
|
2852 |
native method. |
|
2853 |
</error> |
|
2854 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
2855 |
Thread was not suspended and was not the current thread. |
|
2856 |
</error> |
|
2857 |
</errors> |
|
2858 |
</function> |
|
2859 |
||
2860 |
</category> |
|
2861 |
||
2862 |
<category id="ForceEarlyReturn" label="Force Early Return"> |
|
2863 |
<intro> |
|
2864 |
These functions allow an agent to force a method |
|
2865 |
to return at any point during its execution. |
|
2866 |
The method which will return early is referred to as the <i>called method</i>. |
|
2867 |
The called method is the current method |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
2868 |
(as defined by |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
2869 |
<vmspec chapter="3.6"/>) |
1 | 2870 |
for the specified thread at |
2871 |
the time the function is called. |
|
2872 |
<p/> |
|
2873 |
The specified thread must be suspended or must be the current thread. |
|
2874 |
The return occurs when execution of Java programming |
|
2875 |
language code is resumed on this thread. |
|
2876 |
Between calling one of these functions and resumption |
|
2877 |
of thread execution, the state of the stack is undefined. |
|
2878 |
<p/> |
|
2879 |
No further instructions are executed in the called method. |
|
2880 |
Specifically, finally blocks are not executed. |
|
2881 |
Note: this can cause inconsistent states in the application. |
|
2882 |
<p/> |
|
2883 |
A lock acquired by calling the called method |
|
2884 |
(if it is a <code>synchronized</code> method) |
|
2885 |
and locks acquired by entering <code>synchronized</code> |
|
2886 |
blocks within the called method are released. |
|
2887 |
Note: this does not apply to native locks or |
|
2888 |
<code>java.util.concurrent.locks</code> locks. |
|
2889 |
<p/> |
|
2890 |
Events, such as <eventlink id="MethodExit"></eventlink>, |
|
2891 |
are generated as they would be in a normal return. |
|
2892 |
<p/> |
|
2893 |
The called method must be a non-native Java programming |
|
2894 |
language method. |
|
2895 |
Forcing return on a thread with only one frame on the |
|
2896 |
stack causes the thread to exit when resumed. |
|
2897 |
</intro> |
|
2898 |
||
2899 |
<function id="ForceEarlyReturnObject" num="81" since="1.1"> |
|
2900 |
<synopsis>Force Early Return - Object</synopsis> |
|
2901 |
<description> |
|
2902 |
This function can be used to return from a method whose |
|
2903 |
result type is <code>Object</code> |
|
2904 |
or a subclass of <code>Object</code>. |
|
2905 |
</description> |
|
2906 |
<origin>new</origin> |
|
2907 |
<capabilities> |
|
2908 |
<required id="can_force_early_return"></required> |
|
2909 |
</capabilities> |
|
2910 |
<parameters> |
|
2911 |
<param id="thread"> |
|
2912 |
<jthread null="current"/> |
|
2913 |
<description> |
|
2914 |
The thread whose current frame is to return early. |
|
2915 |
</description> |
|
2916 |
</param> |
|
2917 |
<param id="value"> |
|
2918 |
<jobject/> |
|
2919 |
<description> |
|
2920 |
The return value for the called frame. |
|
2921 |
An object or <code>NULL</code>. |
|
2922 |
</description> |
|
2923 |
</param> |
|
2924 |
</parameters> |
|
2925 |
<errors> |
|
2926 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
2927 |
Attempted to return early from a frame |
|
2928 |
corresponding to a native method. |
|
2929 |
Or the implementation is unable to provide |
|
2930 |
this functionality on this frame. |
|
2931 |
</error> |
|
2932 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
2933 |
The result type of the called method is not |
|
2934 |
<code>Object</code> or a subclass of <code>Object</code>. |
|
2935 |
</error> |
|
2936 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
2937 |
The supplied <paramlink id="value"/> is not compatible with the |
|
2938 |
result type of the called method. |
|
2939 |
</error> |
|
2940 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
2941 |
Thread was not the current thread and was not suspended. |
|
2942 |
</error> |
|
2943 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
2944 |
There are no more frames on the call stack. |
|
2945 |
</error> |
|
2946 |
</errors> |
|
2947 |
</function> |
|
2948 |
||
2949 |
<function id="ForceEarlyReturnInt" num="82" since="1.1"> |
|
2950 |
<synopsis>Force Early Return - Int</synopsis> |
|
2951 |
<description> |
|
2952 |
This function can be used to return from a method whose |
|
2953 |
result type is <code>int</code>, <code>short</code>, |
|
2954 |
<code>char</code>, <code>byte</code>, or |
|
2955 |
<code>boolean</code>. |
|
2956 |
</description> |
|
2957 |
<origin>new</origin> |
|
2958 |
<capabilities> |
|
2959 |
<required id="can_force_early_return"></required> |
|
2960 |
</capabilities> |
|
2961 |
<parameters> |
|
2962 |
<param id="thread"> |
|
2963 |
<jthread null="current"/> |
|
2964 |
<description> |
|
2965 |
The thread whose current frame is to return early. |
|
2966 |
</description> |
|
2967 |
</param> |
|
2968 |
<param id="value"> |
|
2969 |
<jint/> |
|
2970 |
<description> |
|
2971 |
The return value for the called frame. |
|
2972 |
</description> |
|
2973 |
</param> |
|
2974 |
</parameters> |
|
2975 |
<errors> |
|
2976 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
2977 |
Attempted to return early from a frame |
|
2978 |
corresponding to a native method. |
|
2979 |
Or the implementation is unable to provide |
|
2980 |
this functionality on this frame. |
|
2981 |
</error> |
|
2982 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
2983 |
The result type of the called method is not |
|
2984 |
<code>int</code>, <code>short</code>, |
|
2985 |
<code>char</code>, <code>byte</code>, or |
|
2986 |
<code>boolean</code>. |
|
2987 |
</error> |
|
2988 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
2989 |
Thread was not the current thread and was not suspended. |
|
2990 |
</error> |
|
2991 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
2992 |
There are no frames on the call stack. |
|
2993 |
</error> |
|
2994 |
</errors> |
|
2995 |
</function> |
|
2996 |
||
2997 |
<function id="ForceEarlyReturnLong" num="83" since="1.1"> |
|
2998 |
<synopsis>Force Early Return - Long</synopsis> |
|
2999 |
<description> |
|
3000 |
This function can be used to return from a method whose |
|
3001 |
result type is <code>long</code>. |
|
3002 |
</description> |
|
3003 |
<origin>new</origin> |
|
3004 |
<capabilities> |
|
3005 |
<required id="can_force_early_return"></required> |
|
3006 |
</capabilities> |
|
3007 |
<parameters> |
|
3008 |
<param id="thread"> |
|
3009 |
<jthread null="current"/> |
|
3010 |
<description> |
|
3011 |
The thread whose current frame is to return early. |
|
3012 |
</description> |
|
3013 |
</param> |
|
3014 |
<param id="value"> |
|
3015 |
<jlong/> |
|
3016 |
<description> |
|
3017 |
The return value for the called frame. |
|
3018 |
</description> |
|
3019 |
</param> |
|
3020 |
</parameters> |
|
3021 |
<errors> |
|
3022 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
3023 |
Attempted to return early from a frame |
|
3024 |
corresponding to a native method. |
|
3025 |
Or the implementation is unable to provide |
|
3026 |
this functionality on this frame. |
|
3027 |
</error> |
|
3028 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
3029 |
The result type of the called method is not <code>long</code>. |
|
3030 |
</error> |
|
3031 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
3032 |
Thread was not the current thread and was not suspended. |
|
3033 |
</error> |
|
3034 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
3035 |
There are no frames on the call stack. |
|
3036 |
</error> |
|
3037 |
</errors> |
|
3038 |
</function> |
|
3039 |
||
3040 |
<function id="ForceEarlyReturnFloat" num="84" since="1.1"> |
|
3041 |
<synopsis>Force Early Return - Float</synopsis> |
|
3042 |
<description> |
|
3043 |
This function can be used to return from a method whose |
|
3044 |
result type is <code>float</code>. |
|
3045 |
</description> |
|
3046 |
<origin>new</origin> |
|
3047 |
<capabilities> |
|
3048 |
<required id="can_force_early_return"></required> |
|
3049 |
</capabilities> |
|
3050 |
<parameters> |
|
3051 |
<param id="thread"> |
|
3052 |
<jthread null="current"/> |
|
3053 |
<description> |
|
3054 |
The thread whose current frame is to return early. |
|
3055 |
</description> |
|
3056 |
</param> |
|
3057 |
<param id="value"> |
|
3058 |
<jfloat/> |
|
3059 |
<description> |
|
3060 |
The return value for the called frame. |
|
3061 |
</description> |
|
3062 |
</param> |
|
3063 |
</parameters> |
|
3064 |
<errors> |
|
3065 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
3066 |
Attempted to return early from a frame |
|
3067 |
corresponding to a native method. |
|
3068 |
Or the implementation is unable to provide |
|
3069 |
this functionality on this frame. |
|
3070 |
</error> |
|
3071 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
3072 |
The result type of the called method is not <code>float</code>. |
|
3073 |
</error> |
|
3074 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
3075 |
Thread was not the current thread and was not suspended. |
|
3076 |
</error> |
|
3077 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
3078 |
There are no frames on the call stack. |
|
3079 |
</error> |
|
3080 |
</errors> |
|
3081 |
</function> |
|
3082 |
||
3083 |
<function id="ForceEarlyReturnDouble" num="85" since="1.1"> |
|
3084 |
<synopsis>Force Early Return - Double</synopsis> |
|
3085 |
<description> |
|
3086 |
This function can be used to return from a method whose |
|
3087 |
result type is <code>double</code>. |
|
3088 |
</description> |
|
3089 |
<origin>new</origin> |
|
3090 |
<capabilities> |
|
3091 |
<required id="can_force_early_return"></required> |
|
3092 |
</capabilities> |
|
3093 |
<parameters> |
|
3094 |
<param id="thread"> |
|
3095 |
<jthread null="current"/> |
|
3096 |
<description> |
|
3097 |
The thread whose current frame is to return early. |
|
3098 |
</description> |
|
3099 |
</param> |
|
3100 |
<param id="value"> |
|
3101 |
<jdouble/> |
|
3102 |
<description> |
|
3103 |
The return value for the called frame. |
|
3104 |
</description> |
|
3105 |
</param> |
|
3106 |
</parameters> |
|
3107 |
<errors> |
|
3108 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
3109 |
Attempted to return early from a frame corresponding to a native method. |
|
3110 |
Or the implementation is unable to provide this functionality on this frame. |
|
3111 |
</error> |
|
3112 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
3113 |
The result type of the called method is not <code>double</code>. |
|
3114 |
</error> |
|
3115 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
3116 |
Thread was not the current thread and was not suspended. |
|
3117 |
</error> |
|
3118 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
3119 |
There are no frames on the call stack. |
|
3120 |
</error> |
|
3121 |
</errors> |
|
3122 |
</function> |
|
3123 |
||
3124 |
<function id="ForceEarlyReturnVoid" num="86" since="1.1"> |
|
3125 |
<synopsis>Force Early Return - Void</synopsis> |
|
3126 |
<description> |
|
3127 |
This function can be used to return from a method with no result type. |
|
3128 |
That is, the called method must be declared <code>void</code>. |
|
3129 |
</description> |
|
3130 |
<origin>new</origin> |
|
3131 |
<capabilities> |
|
3132 |
<required id="can_force_early_return"></required> |
|
3133 |
</capabilities> |
|
3134 |
<parameters> |
|
3135 |
<param id="thread"> |
|
3136 |
<jthread null="current"/> |
|
3137 |
<description> |
|
3138 |
The thread whose current frame is to return early. |
|
3139 |
</description> |
|
3140 |
</param> |
|
3141 |
</parameters> |
|
3142 |
<errors> |
|
3143 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
3144 |
Attempted to return early from a frame |
|
3145 |
corresponding to a native method. |
|
3146 |
Or the implementation is unable to provide |
|
3147 |
this functionality on this frame. |
|
3148 |
</error> |
|
3149 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
3150 |
The called method has a result type. |
|
3151 |
</error> |
|
3152 |
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED"> |
|
3153 |
Thread was not the current thread and was not suspended. |
|
3154 |
</error> |
|
3155 |
<error id="JVMTI_ERROR_NO_MORE_FRAMES"> |
|
3156 |
There are no frames on the call stack. |
|
3157 |
</error> |
|
3158 |
</errors> |
|
3159 |
</function> |
|
3160 |
||
3161 |
</category> |
|
3162 |
||
3163 |
<category id="Heap" label="Heap"> |
|
3164 |
<intro> |
|
3165 |
These functions are used to analyze the heap. |
|
3166 |
Functionality includes the ability to view the objects in the |
|
3167 |
heap and to tag these objects. |
|
3168 |
</intro> |
|
3169 |
||
3170 |
<intro id="objectTags" label="Object Tags"> |
|
3171 |
A <i>tag</i> is a value associated with an object. |
|
3172 |
Tags are explicitly set by the agent using the |
|
3173 |
<functionlink id="SetTag"></functionlink> function or by |
|
3174 |
callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>. |
|
3175 |
<p/> |
|
3176 |
Tags are local to the environment; that is, the tags of one |
|
3177 |
environment are not visible in another. |
|
3178 |
<p/> |
|
3179 |
Tags are <code>jlong</code> values which can be used |
|
3180 |
simply to mark an object or to store a pointer to more detailed |
|
3181 |
information. Objects which have not been tagged have a |
|
3182 |
tag of zero. |
|
3183 |
Setting a tag to zero makes the object untagged. |
|
3184 |
</intro> |
|
3185 |
||
3186 |
<intro id="heapCallbacks" label="Heap Callback Functions"> |
|
3187 |
Heap functions which iterate through the heap and recursively |
|
3188 |
follow object references use agent supplied callback functions |
|
3189 |
to deliver the information. |
|
3190 |
<p/> |
|
3191 |
These heap callback functions must adhere to the following restrictions -- |
|
3192 |
These callbacks must not use JNI functions. |
|
3193 |
These callbacks must not use <jvmti/> functions except |
|
3194 |
<i>callback safe</i> functions which |
|
3195 |
specifically allow such use (see the raw monitor, memory management, |
|
3196 |
and environment local storage functions). |
|
3197 |
<p/> |
|
3198 |
An implementation may invoke a callback on an internal thread or |
|
3199 |
the thread which called the iteration function. |
|
3200 |
Heap callbacks are single threaded -- no more than one callback will |
|
3201 |
be invoked at a time. |
|
3202 |
<p/> |
|
3203 |
The Heap Filter Flags can be used to prevent reporting |
|
3204 |
based on the tag status of an object or its class. |
|
3205 |
If no flags are set (the <code>jint</code> is zero), objects |
|
3206 |
will not be filtered out. |
|
3207 |
||
3208 |
<constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits"> |
|
3209 |
<constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4"> |
|
3210 |
Filter out tagged objects. Objects which are tagged are not included. |
|
3211 |
</constant> |
|
3212 |
<constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8"> |
|
3213 |
Filter out untagged objects. Objects which are not tagged are not included. |
|
3214 |
</constant> |
|
3215 |
<constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10"> |
|
3216 |
Filter out objects with tagged classes. Objects whose class is tagged are not included. |
|
3217 |
</constant> |
|
3218 |
<constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20"> |
|
3219 |
Filter out objects with untagged classes. Objects whose class is not tagged are not included. |
|
3220 |
</constant> |
|
3221 |
</constants> |
|
3222 |
||
3223 |
<p/> |
|
3224 |
The Heap Visit Control Flags are returned by the heap callbacks |
|
3225 |
and can be used to abort the iteration. For the |
|
3226 |
<functionlink id="jvmtiHeapReferenceCallback">Heap |
|
3227 |
Reference Callback</functionlink>, it can also be used |
|
3228 |
to prune the graph of traversed references |
|
3229 |
(<code>JVMTI_VISIT_OBJECTS</code> is not set). |
|
3230 |
||
3231 |
<constants id="jvmtiHeapVisitControl" |
|
3232 |
label="Heap Visit Control Flags" |
|
3233 |
kind="bits" |
|
3234 |
since="1.1"> |
|
3235 |
<constant id="JVMTI_VISIT_OBJECTS" num="0x100"> |
|
3236 |
If we are visiting an object and if this callback |
|
3237 |
was initiated by <functionlink id="FollowReferences"/>, |
|
3238 |
traverse the references of this object. |
|
3239 |
Otherwise ignored. |
|
3240 |
</constant> |
|
3241 |
<constant id="JVMTI_VISIT_ABORT" num="0x8000"> |
|
3242 |
Abort the iteration. Ignore all other bits. |
|
3243 |
</constant> |
|
3244 |
</constants> |
|
3245 |
||
3246 |
<p/> |
|
3247 |
The Heap Reference Enumeration is provided by the |
|
3248 |
<functionlink id="jvmtiHeapReferenceCallback">Heap |
|
3249 |
Reference Callback</functionlink> and |
|
3250 |
<functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field |
|
3251 |
Callback</functionlink> to |
|
3252 |
describe the kind of reference |
|
3253 |
being reported. |
|
3254 |
||
3255 |
<constants id="jvmtiHeapReferenceKind" |
|
3256 |
label="Heap Reference Enumeration" |
|
3257 |
kind="enum" |
|
3258 |
since="1.1"> |
|
3259 |
<constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1"> |
|
3260 |
Reference from an object to its class. |
|
3261 |
</constant> |
|
3262 |
<constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2"> |
|
3263 |
Reference from an object to the value of one of its instance fields. |
|
3264 |
</constant> |
|
3265 |
<constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3"> |
|
3266 |
Reference from an array to one of its elements. |
|
3267 |
</constant> |
|
3268 |
<constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4"> |
|
3269 |
Reference from a class to its class loader. |
|
3270 |
</constant> |
|
3271 |
<constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5"> |
|
3272 |
Reference from a class to its signers array. |
|
3273 |
</constant> |
|
3274 |
<constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6"> |
|
3275 |
Reference from a class to its protection domain. |
|
3276 |
</constant> |
|
3277 |
<constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7"> |
|
3278 |
Reference from a class to one of its interfaces. |
|
3279 |
Note: interfaces are defined via a constant pool reference, |
|
3280 |
so the referenced interfaces may also be reported with a |
|
3281 |
<code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. |
|
3282 |
</constant> |
|
3283 |
<constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8"> |
|
3284 |
Reference from a class to the value of one of its static fields. |
|
3285 |
</constant> |
|
3286 |
<constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9"> |
|
3287 |
Reference from a class to a resolved entry in the constant pool. |
|
3288 |
</constant> |
|
3289 |
<constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10"> |
|
3290 |
Reference from a class to its superclass. |
|
3291 |
A callback is bot sent if the superclass is <code>java.lang.Object</code>. |
|
3292 |
Note: loaded classes define superclasses via a constant pool |
|
3293 |
reference, so the referenced superclass may also be reported with |
|
3294 |
a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind. |
|
3295 |
</constant> |
|
3296 |
<constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21"> |
|
3297 |
Heap root reference: JNI global reference. |
|
3298 |
</constant> |
|
3299 |
<constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22"> |
|
3300 |
Heap root reference: System class. |
|
3301 |
</constant> |
|
3302 |
<constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23"> |
|
3303 |
Heap root reference: monitor. |
|
3304 |
</constant> |
|
3305 |
<constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24"> |
|
3306 |
Heap root reference: local variable on the stack. |
|
3307 |
</constant> |
|
3308 |
<constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25"> |
|
3309 |
Heap root reference: JNI local reference. |
|
3310 |
</constant> |
|
3311 |
<constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26"> |
|
3312 |
Heap root reference: Thread. |
|
3313 |
</constant> |
|
3314 |
<constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27"> |
|
3315 |
Heap root reference: other heap root reference. |
|
3316 |
</constant> |
|
3317 |
</constants> |
|
3318 |
||
3319 |
<p/> |
|
3320 |
Definitions for the single character type descriptors of |
|
3321 |
primitive types. |
|
3322 |
||
3323 |
<constants id="jvmtiPrimitiveType" |
|
3324 |
label="Primitive Type Enumeration" |
|
3325 |
kind="enum" |
|
3326 |
since="1.1"> |
|
3327 |
<constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90"> |
|
3328 |
'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code> |
|
3329 |
</constant> |
|
3330 |
<constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66"> |
|
3331 |
'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code> |
|
3332 |
</constant> |
|
3333 |
<constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67"> |
|
3334 |
'C' - Java programming language <code>char</code> - JNI <code>jchar</code> |
|
3335 |
</constant> |
|
3336 |
<constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83"> |
|
3337 |
'S' - Java programming language <code>short</code> - JNI <code>jshort</code> |
|
3338 |
</constant> |
|
3339 |
<constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73"> |
|
3340 |
'I' - Java programming language <code>int</code> - JNI <code>jint</code> |
|
3341 |
</constant> |
|
3342 |
<constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74"> |
|
3343 |
'J' - Java programming language <code>long</code> - JNI <code>jlong</code> |
|
3344 |
</constant> |
|
3345 |
<constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70"> |
|
3346 |
'F' - Java programming language <code>float</code> - JNI <code>jfloat</code> |
|
3347 |
</constant> |
|
3348 |
<constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68"> |
|
3349 |
'D' - Java programming language <code>double</code> - JNI <code>jdouble</code> |
|
3350 |
</constant> |
|
3351 |
</constants> |
|
3352 |
</intro> |
|
3353 |
||
3354 |
<typedef id="jvmtiHeapReferenceInfoField" |
|
3355 |
label="Reference information structure for Field references" |
|
3356 |
since="1.1"> |
|
3357 |
<description> |
|
3358 |
Reference information returned for |
|
3359 |
<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and |
|
3360 |
<datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. |
|
3361 |
</description> |
|
3362 |
<field id="index"> |
|
3363 |
<jint/> |
|
3364 |
<description> |
|
3365 |
For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the |
|
3366 |
referrer object is not a class or an inteface. |
|
3367 |
In this case, <code>index</code> is the index of the field |
|
3368 |
in the class of the referrer object. |
|
3369 |
This class is referred to below as <i>C</i>. |
|
3370 |
<p/> |
|
3371 |
For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, |
|
3372 |
the referrer object is a class (referred to below as <i>C</i>) |
|
3373 |
or an interface (referred to below as <i>I</i>). |
|
3374 |
In this case, <code>index</code> is the index of the field in |
|
3375 |
that class or interface. |
|
3376 |
<p/> |
|
3377 |
If the referrer object is not an interface, then the field |
|
3378 |
indices are determined as follows: |
|
3379 |
<ul> |
|
3380 |
<li>make a list of all the fields in <i>C</i> and its |
|
3381 |
superclasses, starting with all the fields in |
|
3382 |
<code>java.lang.Object</code> and ending with all the |
|
3383 |
fields in <i>C</i>.</li> |
|
3384 |
<li>Within this list, put |
|
3385 |
the fields for a given class in the order returned by |
|
3386 |
<functionlink id="GetClassFields"/>.</li> |
|
3387 |
<li>Assign the fields in this list indices |
|
3388 |
<i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> |
|
3389 |
is the count of the fields in all the interfaces |
|
3390 |
implemented by <i>C</i>. |
|
3391 |
Note that <i>C</i> implements all interfaces |
|
3392 |
directly implemented by its superclasses; as well |
|
3393 |
as all superinterfaces of these interfaces.</li> |
|
3394 |
</ul> |
|
3395 |
If the referrer object is an interface, then the field |
|
3396 |
indices are determined as follows: |
|
3397 |
<ul> |
|
3398 |
<li>make a list of the fields directly declared in |
|
3399 |
<i>I</i>.</li> |
|
3400 |
<li>Within this list, put |
|
3401 |
the fields in the order returned by |
|
3402 |
<functionlink id="GetClassFields"/>.</li> |
|
3403 |
<li>Assign the fields in this list indices |
|
3404 |
<i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> |
|
3405 |
is the count of the fields in all the superinterfaces |
|
3406 |
of <i>I</i>.</li> |
|
3407 |
</ul> |
|
3408 |
All fields are included in this computation, regardless of |
|
3409 |
field modifier (static, public, private, etc). |
|
3410 |
<p/> |
|
3411 |
For example, given the following classes and interfaces: |
|
3412 |
<example> |
|
3413 |
interface I0 { |
|
3414 |
int p = 0; |
|
3415 |
} |
|
3416 |
||
3417 |
interface I1 extends I0 { |
|
3418 |
int x = 1; |
|
3419 |
} |
|
3420 |
||
3421 |
interface I2 extends I0 { |
|
3422 |
int y = 2; |
|
3423 |
} |
|
3424 |
||
3425 |
class C1 implements I1 { |
|
3426 |
public static int a = 3; |
|
3427 |
private int b = 4; |
|
3428 |
} |
|
3429 |
||
3430 |
class C2 extends C1 implements I2 { |
|
3431 |
static int q = 5; |
|
3432 |
final int r = 6; |
|
3433 |
} |
|
3434 |
</example> |
|
3435 |
Assume that <functionlink id="GetClassFields"/> called on |
|
3436 |
<code>C1</code> returns the fields of <code>C1</code> in the |
|
3437 |
order: a, b; and that the fields of <code>C2</code> are |
|
3438 |
returned in the order: q, r. |
|
3439 |
An instance of class <code>C1</code> will have the |
|
3440 |
following field indices: |
|
3441 |
<dl><dd><table> |
|
3442 |
<tr> |
|
3443 |
<td> |
|
3444 |
a |
|
3445 |
</td> |
|
3446 |
<td> |
|
3447 |
2 |
|
3448 |
</td> |
|
3449 |
<td align="left"> |
|
3450 |
The count of the fields in the interfaces |
|
3451 |
implemented by <code>C1</code> is two (<i>n</i>=2): |
|
3452 |
<code>p</code> of <code>I0</code> |
|
3453 |
and <code>x</code> of <code>I1</code>. |
|
3454 |
</td> |
|
3455 |
</tr> |
|
3456 |
<tr> |
|
3457 |
<td> |
|
3458 |
b |
|
3459 |
</td> |
|
3460 |
<td> |
|
3461 |
3 |
|
3462 |
</td> |
|
3463 |
<td align="left"> |
|
3464 |
the subsequent index. |
|
3465 |
</td> |
|
3466 |
</tr> |
|
3467 |
</table></dd></dl> |
|
3468 |
The class <code>C1</code> will have the same field indices. |
|
3469 |
<p/> |
|
3470 |
An instance of class <code>C2</code> will have the |
|
3471 |
following field indices: |
|
3472 |
<dl><dd><table> |
|
3473 |
<tr> |
|
3474 |
<td> |
|
3475 |
a |
|
3476 |
</td> |
|
3477 |
<td> |
|
3478 |
3 |
|
3479 |
</td> |
|
3480 |
<td align="left"> |
|
3481 |
The count of the fields in the interfaces |
|
3482 |
implemented by <code>C2</code> is three (<i>n</i>=3): |
|
3483 |
<code>p</code> of <code>I0</code>, |
|
3484 |
<code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> |
|
3485 |
(an interface of <code>C2</code>). Note that the field <code>p</code> |
|
3486 |
of <code>I0</code> is only included once. |
|
3487 |
</td> |
|
3488 |
</tr> |
|
3489 |
<tr> |
|
3490 |
<td> |
|
3491 |
b |
|
3492 |
</td> |
|
3493 |
<td> |
|
3494 |
4 |
|
3495 |
</td> |
|
3496 |
<td align="left"> |
|
3497 |
the subsequent index to "a". |
|
3498 |
</td> |
|
3499 |
</tr> |
|
3500 |
<tr> |
|
3501 |
<td> |
|
3502 |
q |
|
3503 |
</td> |
|
3504 |
<td> |
|
3505 |
5 |
|
3506 |
</td> |
|
3507 |
<td align="left"> |
|
3508 |
the subsequent index to "b". |
|
3509 |
</td> |
|
3510 |
</tr> |
|
3511 |
<tr> |
|
3512 |
<td> |
|
3513 |
r |
|
3514 |
</td> |
|
3515 |
<td> |
|
3516 |
6 |
|
3517 |
</td> |
|
3518 |
<td align="left"> |
|
3519 |
the subsequent index to "q". |
|
3520 |
</td> |
|
3521 |
</tr> |
|
3522 |
</table></dd></dl> |
|
3523 |
The class <code>C2</code> will have the same field indices. |
|
3524 |
Note that a field may have a different index depending on the |
|
3525 |
object that is viewing it -- for example field "a" above. |
|
3526 |
Note also: not all field indices may be visible from the |
|
3527 |
callbacks, but all indices are shown for illustrative purposes. |
|
3528 |
<p/> |
|
3529 |
The interface <code>I1</code> will have the |
|
3530 |
following field indices: |
|
3531 |
<dl><dd><table> |
|
3532 |
<tr> |
|
3533 |
<td> |
|
3534 |
x |
|
3535 |
</td> |
|
3536 |
<td> |
|
3537 |
1 |
|
3538 |
</td> |
|
3539 |
<td align="left"> |
|
3540 |
The count of the fields in the superinterfaces |
|
3541 |
of <code>I1</code> is one (<i>n</i>=1): |
|
3542 |
<code>p</code> of <code>I0</code>. |
|
3543 |
</td> |
|
3544 |
</tr> |
|
3545 |
</table></dd></dl> |
|
3546 |
</description> |
|
3547 |
</field> |
|
3548 |
</typedef> |
|
3549 |
||
3550 |
<typedef id="jvmtiHeapReferenceInfoArray" |
|
3551 |
label="Reference information structure for Array references" |
|
3552 |
since="1.1"> |
|
3553 |
<description> |
|
3554 |
Reference information returned for |
|
3555 |
<datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. |
|
3556 |
</description> |
|
3557 |
<field id="index"> |
|
3558 |
<jint/> |
|
3559 |
<description> |
|
3560 |
The array index. |
|
3561 |
</description> |
|
3562 |
</field> |
|
3563 |
</typedef> |
|
3564 |
||
3565 |
<typedef id="jvmtiHeapReferenceInfoConstantPool" |
|
3566 |
label="Reference information structure for Constant Pool references" |
|
3567 |
since="1.1"> |
|
3568 |
<description> |
|
3569 |
Reference information returned for |
|
3570 |
<datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. |
|
3571 |
</description> |
|
3572 |
<field id="index"> |
|
3573 |
<jint/> |
|
3574 |
<description> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
3575 |
The index into the constant pool of the class. See the description in |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
3576 |
<vmspec chapter="4.4"/>. |
1 | 3577 |
</description> |
3578 |
</field> |
|
3579 |
</typedef> |
|
3580 |
||
3581 |
<typedef id="jvmtiHeapReferenceInfoStackLocal" |
|
3582 |
label="Reference information structure for Local Variable references" |
|
3583 |
since="1.1"> |
|
3584 |
<description> |
|
3585 |
Reference information returned for |
|
3586 |
<datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. |
|
3587 |
</description> |
|
3588 |
<field id="thread_tag"> |
|
3589 |
<jlong/> |
|
3590 |
<description> |
|
3591 |
The tag of the thread corresponding to this stack, zero if not tagged. |
|
3592 |
</description> |
|
3593 |
</field> |
|
3594 |
<field id="thread_id"> |
|
3595 |
<jlong/> |
|
3596 |
<description> |
|
3597 |
The unique thread ID of the thread corresponding to this stack. |
|
3598 |
</description> |
|
3599 |
</field> |
|
3600 |
<field id="depth"> |
|
3601 |
<jint/> |
|
3602 |
<description> |
|
3603 |
The depth of the frame. |
|
3604 |
</description> |
|
3605 |
</field> |
|
3606 |
<field id="method"> |
|
3607 |
<jmethodID/> |
|
3608 |
<description> |
|
3609 |
The method executing in this frame. |
|
3610 |
</description> |
|
3611 |
</field> |
|
3612 |
<field id="location"> |
|
3613 |
<jlocation/> |
|
3614 |
<description> |
|
3615 |
The currently executing location in this frame. |
|
3616 |
</description> |
|
3617 |
</field> |
|
3618 |
<field id="slot"> |
|
3619 |
<jint/> |
|
3620 |
<description> |
|
3621 |
The slot number of the local variable. |
|
3622 |
</description> |
|
3623 |
</field> |
|
3624 |
</typedef> |
|
3625 |
||
3626 |
<typedef id="jvmtiHeapReferenceInfoJniLocal" |
|
3627 |
label="Reference information structure for JNI local references" |
|
3628 |
since="1.1"> |
|
3629 |
<description> |
|
3630 |
Reference information returned for |
|
3631 |
<datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. |
|
3632 |
</description> |
|
3633 |
<field id="thread_tag"> |
|
3634 |
<jlong/> |
|
3635 |
<description> |
|
3636 |
The tag of the thread corresponding to this stack, zero if not tagged. |
|
3637 |
</description> |
|
3638 |
</field> |
|
3639 |
<field id="thread_id"> |
|
3640 |
<jlong/> |
|
3641 |
<description> |
|
3642 |
The unique thread ID of the thread corresponding to this stack. |
|
3643 |
</description> |
|
3644 |
</field> |
|
3645 |
<field id="depth"> |
|
3646 |
<jint/> |
|
3647 |
<description> |
|
3648 |
The depth of the frame. |
|
3649 |
</description> |
|
3650 |
</field> |
|
3651 |
<field id="method"> |
|
3652 |
<jmethodID/> |
|
3653 |
<description> |
|
3654 |
The method executing in this frame. |
|
3655 |
</description> |
|
3656 |
</field> |
|
3657 |
</typedef> |
|
3658 |
||
3659 |
<typedef id="jvmtiHeapReferenceInfoReserved" |
|
3660 |
label="Reference information structure for Other references" |
|
3661 |
since="1.1"> |
|
3662 |
<description> |
|
3663 |
Reference information returned for other references. |
|
3664 |
</description> |
|
3665 |
<field id="reserved1"> |
|
3666 |
<jlong/> |
|
3667 |
<description> |
|
3668 |
reserved for future use. |
|
3669 |
</description> |
|
3670 |
</field> |
|
3671 |
<field id="reserved2"> |
|
3672 |
<jlong/> |
|
3673 |
<description> |
|
3674 |
reserved for future use. |
|
3675 |
</description> |
|
3676 |
</field> |
|
3677 |
<field id="reserved3"> |
|
3678 |
<jlong/> |
|
3679 |
<description> |
|
3680 |
reserved for future use. |
|
3681 |
</description> |
|
3682 |
</field> |
|
3683 |
<field id="reserved4"> |
|
3684 |
<jlong/> |
|
3685 |
<description> |
|
3686 |
reserved for future use. |
|
3687 |
</description> |
|
3688 |
</field> |
|
3689 |
<field id="reserved5"> |
|
3690 |
<jlong/> |
|
3691 |
<description> |
|
3692 |
reserved for future use. |
|
3693 |
</description> |
|
3694 |
</field> |
|
3695 |
<field id="reserved6"> |
|
3696 |
<jlong/> |
|
3697 |
<description> |
|
3698 |
reserved for future use. |
|
3699 |
</description> |
|
3700 |
</field> |
|
3701 |
<field id="reserved7"> |
|
3702 |
<jlong/> |
|
3703 |
<description> |
|
3704 |
reserved for future use. |
|
3705 |
</description> |
|
3706 |
</field> |
|
3707 |
<field id="reserved8"> |
|
3708 |
<jlong/> |
|
3709 |
<description> |
|
3710 |
reserved for future use. |
|
3711 |
</description> |
|
3712 |
</field> |
|
3713 |
</typedef> |
|
3714 |
||
3715 |
<uniontypedef id="jvmtiHeapReferenceInfo" |
|
3716 |
label="Reference information structure" |
|
3717 |
since="1.1"> |
|
3718 |
<description> |
|
3719 |
The information returned about referrers. |
|
3720 |
Represented as a union of the various kinds of reference information. |
|
3721 |
</description> |
|
3722 |
<field id="field"> |
|
3723 |
<struct>jvmtiHeapReferenceInfoField</struct> |
|
3724 |
<description> |
|
3725 |
The referrer information for |
|
3726 |
<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> |
|
3727 |
and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references. |
|
3728 |
</description> |
|
3729 |
</field> |
|
3730 |
<field id="array"> |
|
3731 |
<struct>jvmtiHeapReferenceInfoArray</struct> |
|
3732 |
<description> |
|
3733 |
The referrer information for |
|
3734 |
For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references. |
|
3735 |
</description> |
|
3736 |
</field> |
|
3737 |
<field id="constant_pool"> |
|
3738 |
<struct>jvmtiHeapReferenceInfoConstantPool</struct> |
|
3739 |
<description> |
|
3740 |
The referrer information for |
|
3741 |
For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references. |
|
3742 |
</description> |
|
3743 |
</field> |
|
3744 |
<field id="stack_local"> |
|
3745 |
<struct>jvmtiHeapReferenceInfoStackLocal</struct> |
|
3746 |
<description> |
|
3747 |
The referrer information for |
|
3748 |
For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references. |
|
3749 |
</description> |
|
3750 |
</field> |
|
3751 |
<field id="jni_local"> |
|
3752 |
<struct>jvmtiHeapReferenceInfoJniLocal</struct> |
|
3753 |
<description> |
|
3754 |
The referrer information for |
|
3755 |
For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references. |
|
3756 |
</description> |
|
3757 |
</field> |
|
3758 |
<field id="other"> |
|
3759 |
<struct>jvmtiHeapReferenceInfoReserved</struct> |
|
3760 |
<description> |
|
3761 |
reserved for future use. |
|
3762 |
</description> |
|
3763 |
</field> |
|
3764 |
</uniontypedef> |
|
3765 |
||
3766 |
<typedef id="jvmtiHeapCallbacks" |
|
3767 |
label="Heap callback function structure" |
|
3768 |
since="1.1"> |
|
3769 |
<field id="heap_iteration_callback"> |
|
3770 |
<ptrtype> |
|
3771 |
<struct>jvmtiHeapIterationCallback</struct> |
|
3772 |
</ptrtype> |
|
3773 |
<description> |
|
3774 |
The callback to be called to describe an |
|
3775 |
object in the heap. Used by the |
|
3776 |
<functionlink id="IterateThroughHeap"/> function, ignored by the |
|
3777 |
<functionlink id="FollowReferences"/> function. |
|
3778 |
</description> |
|
3779 |
</field> |
|
3780 |
<field id="heap_reference_callback"> |
|
3781 |
<ptrtype> |
|
3782 |
<struct>jvmtiHeapReferenceCallback</struct> |
|
3783 |
</ptrtype> |
|
3784 |
<description> |
|
3785 |
The callback to be called to describe an |
|
3786 |
object reference. Used by the |
|
3787 |
<functionlink id="FollowReferences"/> function, ignored by the |
|
3788 |
<functionlink id="IterateThroughHeap"/> function. |
|
3789 |
</description> |
|
3790 |
</field> |
|
3791 |
<field id="primitive_field_callback"> |
|
3792 |
<ptrtype> |
|
3793 |
<struct>jvmtiPrimitiveFieldCallback</struct> |
|
3794 |
</ptrtype> |
|
3795 |
<description> |
|
3796 |
The callback to be called to describe a |
|
3797 |
primitive field. |
|
3798 |
</description> |
|
3799 |
</field> |
|
3800 |
<field id="array_primitive_value_callback"> |
|
3801 |
<ptrtype> |
|
3802 |
<struct>jvmtiArrayPrimitiveValueCallback</struct> |
|
3803 |
</ptrtype> |
|
3804 |
<description> |
|
3805 |
The callback to be called to describe an |
|
3806 |
array of primitive values. |
|
3807 |
</description> |
|
3808 |
</field> |
|
3809 |
<field id="string_primitive_value_callback"> |
|
3810 |
<ptrtype> |
|
3811 |
<struct>jvmtiStringPrimitiveValueCallback</struct> |
|
3812 |
</ptrtype> |
|
3813 |
<description> |
|
3814 |
The callback to be called to describe a String value. |
|
3815 |
</description> |
|
3816 |
</field> |
|
3817 |
<field id="reserved5"> |
|
3818 |
<ptrtype> |
|
3819 |
<struct>jvmtiReservedCallback</struct> |
|
3820 |
</ptrtype> |
|
3821 |
<description> |
|
3822 |
Reserved for future use.. |
|
3823 |
</description> |
|
3824 |
</field> |
|
3825 |
<field id="reserved6"> |
|
3826 |
<ptrtype> |
|
3827 |
<struct>jvmtiReservedCallback</struct> |
|
3828 |
</ptrtype> |
|
3829 |
<description> |
|
3830 |
Reserved for future use.. |
|
3831 |
</description> |
|
3832 |
</field> |
|
3833 |
<field id="reserved7"> |
|
3834 |
<ptrtype> |
|
3835 |
<struct>jvmtiReservedCallback</struct> |
|
3836 |
</ptrtype> |
|
3837 |
<description> |
|
3838 |
Reserved for future use.. |
|
3839 |
</description> |
|
3840 |
</field> |
|
3841 |
<field id="reserved8"> |
|
3842 |
<ptrtype> |
|
3843 |
<struct>jvmtiReservedCallback</struct> |
|
3844 |
</ptrtype> |
|
3845 |
<description> |
|
3846 |
Reserved for future use.. |
|
3847 |
</description> |
|
3848 |
</field> |
|
3849 |
<field id="reserved9"> |
|
3850 |
<ptrtype> |
|
3851 |
<struct>jvmtiReservedCallback</struct> |
|
3852 |
</ptrtype> |
|
3853 |
<description> |
|
3854 |
Reserved for future use.. |
|
3855 |
</description> |
|
3856 |
</field> |
|
3857 |
<field id="reserved10"> |
|
3858 |
<ptrtype> |
|
3859 |
<struct>jvmtiReservedCallback</struct> |
|
3860 |
</ptrtype> |
|
3861 |
<description> |
|
3862 |
Reserved for future use.. |
|
3863 |
</description> |
|
3864 |
</field> |
|
3865 |
<field id="reserved11"> |
|
3866 |
<ptrtype> |
|
3867 |
<struct>jvmtiReservedCallback</struct> |
|
3868 |
</ptrtype> |
|
3869 |
<description> |
|
3870 |
Reserved for future use.. |
|
3871 |
</description> |
|
3872 |
</field> |
|
3873 |
<field id="reserved12"> |
|
3874 |
<ptrtype> |
|
3875 |
<struct>jvmtiReservedCallback</struct> |
|
3876 |
</ptrtype> |
|
3877 |
<description> |
|
3878 |
Reserved for future use.. |
|
3879 |
</description> |
|
3880 |
</field> |
|
3881 |
<field id="reserved13"> |
|
3882 |
<ptrtype> |
|
3883 |
<struct>jvmtiReservedCallback</struct> |
|
3884 |
</ptrtype> |
|
3885 |
<description> |
|
3886 |
Reserved for future use.. |
|
3887 |
</description> |
|
3888 |
</field> |
|
3889 |
<field id="reserved14"> |
|
3890 |
<ptrtype> |
|
3891 |
<struct>jvmtiReservedCallback</struct> |
|
3892 |
</ptrtype> |
|
3893 |
<description> |
|
3894 |
Reserved for future use.. |
|
3895 |
</description> |
|
3896 |
</field> |
|
3897 |
<field id="reserved15"> |
|
3898 |
<ptrtype> |
|
3899 |
<struct>jvmtiReservedCallback</struct> |
|
3900 |
</ptrtype> |
|
3901 |
<description> |
|
3902 |
Reserved for future use.. |
|
3903 |
</description> |
|
3904 |
</field> |
|
3905 |
</typedef> |
|
3906 |
||
3907 |
||
3908 |
<intro> |
|
3909 |
<rationale> |
|
3910 |
The heap dumping functionality (below) uses a callback |
|
3911 |
for each object. While it would seem that a buffered approach |
|
3912 |
would provide better throughput, tests do |
|
3913 |
not show this to be the case--possibly due to locality of |
|
3914 |
memory reference or array access overhead. |
|
3915 |
</rationale> |
|
3916 |
||
3917 |
<issue> |
|
3918 |
Still under investigation as to if java.lang.ref references |
|
3919 |
are reported as a different type of reference. |
|
3920 |
</issue> |
|
3921 |
||
3922 |
<issue> |
|
3923 |
Should or can an indication of the cost or relative cost of |
|
3924 |
these operations be included? |
|
3925 |
</issue> |
|
3926 |
||
3927 |
</intro> |
|
3928 |
||
3929 |
<callback id="jvmtiHeapIterationCallback" since="1.1"> |
|
3930 |
<jint/> |
|
3931 |
<synopsis>Heap Iteration Callback</synopsis> |
|
3932 |
<description> |
|
3933 |
Agent supplied callback function. |
|
3934 |
Describes (but does not pass in) an object in the heap. |
|
3935 |
<p/> |
|
3936 |
This function should return a bit vector of the desired |
|
3937 |
<datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. |
|
3938 |
This will determine if the entire iteration should be aborted |
|
3939 |
(the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). |
|
3940 |
<p/> |
|
3941 |
See the <internallink id="heapCallbacks">heap callback |
|
3942 |
function restrictions</internallink>. |
|
3943 |
</description> |
|
3944 |
<parameters> |
|
3945 |
<param id="class_tag"> |
|
3946 |
<jlong/> |
|
3947 |
<description> |
|
3948 |
The tag of the class of object (zero if the class is not tagged). |
|
3949 |
If the object represents a runtime class, |
|
3950 |
the <code>class_tag</code> is the tag |
|
3951 |
associated with <code>java.lang.Class</code> |
|
3952 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
3953 |
</description> |
|
3954 |
</param> |
|
3955 |
<param id="size"> |
|
3956 |
<jlong/> |
|
3957 |
<description> |
|
3958 |
Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. |
|
3959 |
</description> |
|
3960 |
</param> |
|
3961 |
<param id="tag_ptr"> |
|
3962 |
<outptr><jlong/></outptr> |
|
3963 |
<description> |
|
3964 |
The object tag value, or zero if the object is not tagged. |
|
3965 |
To set the tag value to be associated with the object |
|
3966 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
3967 |
</description> |
|
3968 |
</param> |
|
3969 |
<param id="length"> |
|
3970 |
<jint/> |
|
3971 |
<description> |
|
3972 |
If this object is an array, the length of the array. Otherwise negative one (-1). |
|
3973 |
</description> |
|
3974 |
</param> |
|
3975 |
<param id="user_data"> |
|
3976 |
<outptr><void/></outptr> |
|
3977 |
<description> |
|
3978 |
The user supplied data that was passed into the iteration function. |
|
3979 |
</description> |
|
3980 |
</param> |
|
3981 |
</parameters> |
|
3982 |
</callback> |
|
3983 |
||
3984 |
<callback id="jvmtiHeapReferenceCallback" since="1.1"> |
|
3985 |
<jint/> |
|
3986 |
<synopsis>Heap Reference Callback</synopsis> |
|
3987 |
<description> |
|
3988 |
Agent supplied callback function. |
|
3989 |
Describes a reference from an object or the VM (the referrer) to another object |
|
3990 |
(the referree) or a heap root to a referree. |
|
3991 |
<p/> |
|
3992 |
This function should return a bit vector of the desired |
|
3993 |
<datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. |
|
3994 |
This will determine if the objects referenced by the referree |
|
3995 |
should be visited or if the entire iteration should be aborted. |
|
3996 |
<p/> |
|
3997 |
See the <internallink id="heapCallbacks">heap callback |
|
3998 |
function restrictions</internallink>. |
|
3999 |
</description> |
|
4000 |
<parameters> |
|
4001 |
<param id="reference_kind"> |
|
4002 |
<enum>jvmtiHeapReferenceKind</enum> |
|
4003 |
<description> |
|
4004 |
The kind of reference. |
|
4005 |
</description> |
|
4006 |
</param> |
|
4007 |
<param id="reference_info"> |
|
4008 |
<inptr> |
|
4009 |
<struct>jvmtiHeapReferenceInfo</struct> |
|
4010 |
</inptr> |
|
4011 |
<description> |
|
4012 |
Details about the reference. |
|
14287 | 4013 |
Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is |
1 | 4014 |
<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, |
4015 |
<datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>, |
|
4016 |
<datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>, |
|
4017 |
<datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, |
|
4018 |
<datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>, |
|
4019 |
or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>. |
|
4020 |
Otherwise <code>NULL</code>. |
|
4021 |
</description> |
|
4022 |
</param> |
|
4023 |
<param id="class_tag"> |
|
4024 |
<jlong/> |
|
4025 |
<description> |
|
4026 |
The tag of the class of referree object (zero if the class is not tagged). |
|
4027 |
If the referree object represents a runtime class, |
|
4028 |
the <code>class_tag</code> is the tag |
|
4029 |
associated with <code>java.lang.Class</code> |
|
4030 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
4031 |
</description> |
|
4032 |
</param> |
|
4033 |
<param id="referrer_class_tag"> |
|
4034 |
<jlong/> |
|
4035 |
<description> |
|
4036 |
The tag of the class of the referrer object (zero if the class is not tagged |
|
4037 |
or the referree is a heap root). If the referrer object represents a runtime |
|
4038 |
class, the <code>referrer_class_tag</code> is the tag associated with |
|
4039 |
the <code>java.lang.Class</code> |
|
4040 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
4041 |
</description> |
|
4042 |
</param> |
|
4043 |
<param id="size"> |
|
4044 |
<jlong/> |
|
4045 |
<description> |
|
4046 |
Size of the referree object (in bytes). |
|
4047 |
See <functionlink id="GetObjectSize"/>. |
|
4048 |
</description> |
|
4049 |
</param> |
|
4050 |
<param id="tag_ptr"> |
|
4051 |
<outptr><jlong/></outptr> |
|
4052 |
<description> |
|
4053 |
Points to the referree object tag value, or zero if the object is not |
|
4054 |
tagged. |
|
4055 |
To set the tag value to be associated with the object |
|
4056 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
4057 |
</description> |
|
4058 |
</param> |
|
4059 |
<param id="referrer_tag_ptr"> |
|
4060 |
<outptr><jlong/></outptr> |
|
4061 |
<description> |
|
4062 |
Points to the tag of the referrer object, or |
|
4063 |
points to the zero if the referrer |
|
4064 |
object is not tagged. |
|
4065 |
<code>NULL</code> if the referrer in not an object (that is, |
|
4066 |
this callback is reporting a heap root). |
|
4067 |
To set the tag value to be associated with the referrer object |
|
4068 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
4069 |
If this callback is reporting a reference from an object to itself, |
|
4070 |
<code>referrer_tag_ptr == tag_ptr</code>. |
|
4071 |
</description> |
|
4072 |
</param> |
|
4073 |
<param id="length"> |
|
4074 |
<jint/> |
|
4075 |
<description> |
|
4076 |
If this object is an array, the length of the array. Otherwise negative one (-1). |
|
4077 |
</description> |
|
4078 |
</param> |
|
4079 |
<param id="user_data"> |
|
4080 |
<outptr><void/></outptr> |
|
4081 |
<description> |
|
4082 |
The user supplied data that was passed into the iteration function. |
|
4083 |
</description> |
|
4084 |
</param> |
|
4085 |
</parameters> |
|
4086 |
</callback> |
|
4087 |
||
4088 |
<callback id="jvmtiPrimitiveFieldCallback" since="1.1"> |
|
4089 |
<jint/> |
|
4090 |
<synopsis>Primitive Field Callback</synopsis> |
|
4091 |
<description> |
|
4092 |
Agent supplied callback function which |
|
4093 |
describes a primitive field of an object (<i>the object</i>). |
|
4094 |
A primitive field is a field whose type is a primitive type. |
|
4095 |
This callback will describe a static field if the object is a class, |
|
4096 |
and otherwise will describe an instance field. |
|
4097 |
<p/> |
|
4098 |
This function should return a bit vector of the desired |
|
4099 |
<datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. |
|
4100 |
This will determine if the entire iteration should be aborted |
|
4101 |
(the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). |
|
4102 |
<p/> |
|
4103 |
See the <internallink id="heapCallbacks">heap callback |
|
4104 |
function restrictions</internallink>. |
|
4105 |
</description> |
|
4106 |
<parameters> |
|
4107 |
<param id="kind"> |
|
4108 |
<enum>jvmtiHeapReferenceKind</enum> |
|
4109 |
<description> |
|
4110 |
The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or |
|
4111 |
<datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>). |
|
4112 |
</description> |
|
4113 |
</param> |
|
4114 |
<param id="info"> |
|
4115 |
<inptr> |
|
4116 |
<struct>jvmtiHeapReferenceInfo</struct> |
|
4117 |
</inptr> |
|
4118 |
<description> |
|
4119 |
Which field (the field index). |
|
4120 |
</description> |
|
4121 |
</param> |
|
4122 |
<param id="object_class_tag"> |
|
4123 |
<jlong/> |
|
4124 |
<description> |
|
4125 |
The tag of the class of the object (zero if the class is not tagged). |
|
4126 |
If the object represents a runtime class, the |
|
4127 |
<code>object_class_tag</code> is the tag |
|
4128 |
associated with <code>java.lang.Class</code> |
|
4129 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
4130 |
</description> |
|
4131 |
</param> |
|
4132 |
<param id="object_tag_ptr"> |
|
4133 |
<outptr><jlong/></outptr> |
|
4134 |
<description> |
|
4135 |
Points to the tag of the object, or zero if the object is not |
|
4136 |
tagged. |
|
4137 |
To set the tag value to be associated with the object |
|
4138 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
4139 |
</description> |
|
4140 |
</param> |
|
4141 |
<param id="value"> |
|
4142 |
<jvalue/> |
|
4143 |
<description> |
|
4144 |
The value of the field. |
|
4145 |
</description> |
|
4146 |
</param> |
|
4147 |
<param id="value_type"> |
|
4148 |
<enum>jvmtiPrimitiveType</enum> |
|
4149 |
<description> |
|
4150 |
The type of the field. |
|
4151 |
</description> |
|
4152 |
</param> |
|
4153 |
<param id="user_data"> |
|
4154 |
<outptr><void/></outptr> |
|
4155 |
<description> |
|
4156 |
The user supplied data that was passed into the iteration function. |
|
4157 |
</description> |
|
4158 |
</param> |
|
4159 |
</parameters> |
|
4160 |
</callback> |
|
4161 |
||
4162 |
<callback id="jvmtiArrayPrimitiveValueCallback" since="1.1"> |
|
4163 |
<jint/> |
|
4164 |
<synopsis>Array Primitive Value Callback</synopsis> |
|
4165 |
<description> |
|
4166 |
Agent supplied callback function. |
|
4167 |
Describes the values in an array of a primitive type. |
|
4168 |
<p/> |
|
4169 |
This function should return a bit vector of the desired |
|
4170 |
<datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. |
|
4171 |
This will determine if the entire iteration should be aborted |
|
4172 |
(the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). |
|
4173 |
<p/> |
|
4174 |
See the <internallink id="heapCallbacks">heap callback |
|
4175 |
function restrictions</internallink>. |
|
4176 |
</description> |
|
4177 |
<parameters> |
|
4178 |
<param id="class_tag"> |
|
4179 |
<jlong/> |
|
4180 |
<description> |
|
4181 |
The tag of the class of the array object (zero if the class is not tagged). |
|
4182 |
</description> |
|
4183 |
</param> |
|
4184 |
<param id="size"> |
|
4185 |
<jlong/> |
|
4186 |
<description> |
|
4187 |
Size of the array (in bytes). |
|
4188 |
See <functionlink id="GetObjectSize"/>. |
|
4189 |
</description> |
|
4190 |
</param> |
|
4191 |
<param id="tag_ptr"> |
|
4192 |
<outptr><jlong/></outptr> |
|
4193 |
<description> |
|
4194 |
Points to the tag of the array object, or zero if the object is not |
|
4195 |
tagged. |
|
4196 |
To set the tag value to be associated with the object |
|
4197 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
4198 |
</description> |
|
4199 |
</param> |
|
4200 |
<param id="element_count"> |
|
4201 |
<jint/> |
|
4202 |
<description> |
|
4203 |
The length of the primitive array. |
|
4204 |
</description> |
|
4205 |
</param> |
|
4206 |
<param id="element_type"> |
|
4207 |
<enum>jvmtiPrimitiveType</enum> |
|
4208 |
<description> |
|
4209 |
The type of the elements of the array. |
|
4210 |
</description> |
|
4211 |
</param> |
|
4212 |
<param id="elements"> |
|
4213 |
<vmbuf><void/></vmbuf> |
|
4214 |
<description> |
|
4215 |
The elements of the array in a packed array of <code>element_count</code> |
|
4216 |
items of <code>element_type</code> size each. |
|
4217 |
</description> |
|
4218 |
</param> |
|
4219 |
<param id="user_data"> |
|
4220 |
<outptr><void/></outptr> |
|
4221 |
<description> |
|
4222 |
The user supplied data that was passed into the iteration function. |
|
4223 |
</description> |
|
4224 |
</param> |
|
4225 |
</parameters> |
|
4226 |
</callback> |
|
4227 |
||
4228 |
<callback id="jvmtiStringPrimitiveValueCallback" since="1.1"> |
|
4229 |
<jint/> |
|
4230 |
<synopsis>String Primitive Value Callback</synopsis> |
|
4231 |
<description> |
|
4232 |
Agent supplied callback function. |
|
4233 |
Describes the value of a java.lang.String. |
|
4234 |
<p/> |
|
4235 |
This function should return a bit vector of the desired |
|
4236 |
<datalink id="jvmtiHeapVisitControl">visit control flags</datalink>. |
|
4237 |
This will determine if the entire iteration should be aborted |
|
4238 |
(the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored). |
|
4239 |
<p/> |
|
4240 |
See the <internallink id="heapCallbacks">heap callback |
|
4241 |
function restrictions</internallink>. |
|
4242 |
</description> |
|
4243 |
<parameters> |
|
4244 |
<param id="class_tag"> |
|
4245 |
<jlong/> |
|
4246 |
<description> |
|
4247 |
The tag of the class of the String class (zero if the class is not tagged). |
|
4248 |
<issue>Is this needed?</issue> |
|
4249 |
</description> |
|
4250 |
</param> |
|
4251 |
<param id="size"> |
|
4252 |
<jlong/> |
|
4253 |
<description> |
|
4254 |
Size of the string (in bytes). |
|
4255 |
See <functionlink id="GetObjectSize"/>. |
|
4256 |
</description> |
|
4257 |
</param> |
|
4258 |
<param id="tag_ptr"> |
|
4259 |
<outptr><jlong/></outptr> |
|
4260 |
<description> |
|
4261 |
Points to the tag of the String object, or zero if the object is not |
|
4262 |
tagged. |
|
4263 |
To set the tag value to be associated with the object |
|
4264 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
4265 |
</description> |
|
4266 |
</param> |
|
4267 |
<param id="value"> |
|
4268 |
<vmbuf><jchar/></vmbuf> |
|
4269 |
<description> |
|
4270 |
The value of the String, encoded as a Unicode string. |
|
4271 |
</description> |
|
4272 |
</param> |
|
4273 |
<param id="value_length"> |
|
4274 |
<jint/> |
|
4275 |
<description> |
|
4276 |
The length of the string. |
|
4277 |
The length is equal to the number of 16-bit Unicode |
|
4278 |
characters in the string. |
|
4279 |
</description> |
|
4280 |
</param> |
|
4281 |
<param id="user_data"> |
|
4282 |
<outptr><void/></outptr> |
|
4283 |
<description> |
|
4284 |
The user supplied data that was passed into the iteration function. |
|
4285 |
</description> |
|
4286 |
</param> |
|
4287 |
</parameters> |
|
4288 |
</callback> |
|
4289 |
||
4290 |
||
4291 |
<callback id="jvmtiReservedCallback" since="1.1"> |
|
4292 |
<jint/> |
|
4293 |
<synopsis>reserved for future use Callback</synopsis> |
|
4294 |
<description> |
|
4295 |
Placeholder -- reserved for future use. |
|
4296 |
</description> |
|
4297 |
<parameters> |
|
4298 |
</parameters> |
|
4299 |
</callback> |
|
4300 |
||
4301 |
<function id="FollowReferences" num="115" since="1.1"> |
|
4302 |
<synopsis>Follow References</synopsis> |
|
4303 |
<description> |
|
4304 |
This function initiates a traversal over the objects that are |
|
4305 |
directly and indirectly reachable from the specified object or, |
|
4306 |
if <code>initial_object</code> is not specified, all objects |
|
4307 |
reachable from the heap roots. |
|
4308 |
The heap root are the set of system classes, |
|
4309 |
JNI globals, references from thread stacks, and other objects used as roots |
|
4310 |
for the purposes of garbage collection. |
|
4311 |
<p/> |
|
4312 |
This function operates by traversing the reference graph. |
|
4313 |
Let <i>A</i>, <i>B</i>, ... represent objects. |
|
4314 |
When a reference from <i>A</i> to <i>B</i> is traversed, |
|
4315 |
when a reference from a heap root to <i>B</i> is traversed, |
|
4316 |
or when <i>B</i> is specified as the <paramlink id="initial_object"/>, |
|
4317 |
then <i>B</i> is said to be <i>visited</i>. |
|
4318 |
A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> |
|
4319 |
is visited. |
|
4320 |
References are reported in the same order that the references are traversed. |
|
4321 |
Object references are reported by invoking the agent supplied |
|
4322 |
callback function <functionlink id="jvmtiHeapReferenceCallback"/>. |
|
4323 |
In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known |
|
4324 |
as the <i>referrer</i> and <i>B</i> as the <i>referree</i>. |
|
4325 |
The callback is invoked exactly once for each reference from a referrer; |
|
4326 |
this is true even if there are reference cycles or multiple paths to |
|
4327 |
the referrer. |
|
4328 |
There may be more than one reference between a referrer and a referree, |
|
4329 |
each reference is reported. |
|
4330 |
These references may be distinguished by examining the |
|
4331 |
<datalink |
|
4332 |
id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink> |
|
4333 |
and |
|
4334 |
<datalink |
|
4335 |
id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink> |
|
4336 |
parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback. |
|
4337 |
<p/> |
|
4338 |
This function reports a Java programming language view of object references, |
|
4339 |
not a virtual machine implementation view. The following object references |
|
4340 |
are reported when they are non-null: |
|
4341 |
<ul> |
|
4342 |
<li>Instance objects report references to each non-primitive instance fields |
|
4343 |
(including inherited fields).</li> |
|
4344 |
<li>Instance objects report a reference to the object type (class).</li> |
|
4345 |
<li>Classes report a reference to the superclass and directly |
|
4346 |
implemented/extended interfaces.</li> |
|
4347 |
<li>Classes report a reference to the class loader, protection domain, |
|
4348 |
signers, and resolved entries in the constant pool.</li> |
|
4349 |
<li>Classes report a reference to each directly declared non-primitive |
|
4350 |
static field.</li> |
|
4351 |
<li>Arrays report a reference to the array type (class) and each |
|
4352 |
array element.</li> |
|
4353 |
<li>Primitive arrays report a reference to the array type.</li> |
|
4354 |
</ul> |
|
4355 |
<p/> |
|
4356 |
This function can also be used to examine primitive (non-object) values. |
|
4357 |
The primitive value of an array or String |
|
4358 |
is reported after the object has been visited; |
|
4359 |
it is reported by invoking the agent supplied callback function |
|
4360 |
<functionlink id="jvmtiArrayPrimitiveValueCallback"/> or |
|
4361 |
<functionlink id="jvmtiStringPrimitiveValueCallback"/>. |
|
4362 |
A primitive field |
|
4363 |
is reported after the object with that field is visited; |
|
4364 |
it is reported by invoking the agent supplied callback function |
|
4365 |
<functionlink id="jvmtiPrimitiveFieldCallback"/>. |
|
4366 |
<p/> |
|
4367 |
Whether a callback is provided or is <code>NULL</code> only determines |
|
4368 |
whether the callback will be invoked, it does not influence |
|
4369 |
which objects are visited nor does it influence whether other callbacks |
|
4370 |
will be invoked. |
|
4371 |
However, the |
|
4372 |
<datalink id="jvmtiHeapVisitControl">visit control flags</datalink> |
|
4373 |
returned by <functionlink id="jvmtiHeapReferenceCallback"/> |
|
4374 |
do determine if the objects referenced by the |
|
4375 |
current object as visited. |
|
4376 |
The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> |
|
4377 |
and <paramlink id="klass"/> provided as parameters to this function |
|
4378 |
do not control which objects are visited but they do control which |
|
4379 |
objects and primitive values are reported by the callbacks. |
|
4380 |
For example, if the only callback that was set is |
|
14287 | 4381 |
<fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
1 | 4382 |
is set to the array of bytes class, then only arrays of byte will be |
4383 |
reported. |
|
4384 |
The table below summarizes this: |
|
4385 |
<p/> |
|
4386 |
<table> |
|
4387 |
<tr> |
|
4388 |
<th/> |
|
4389 |
<th> |
|
4390 |
Controls objects visited |
|
4391 |
</th> |
|
4392 |
<th> |
|
4393 |
Controls objects reported |
|
4394 |
</th> |
|
4395 |
<th> |
|
4396 |
Controls primitives reported |
|
4397 |
</th> |
|
4398 |
</tr> |
|
4399 |
<tr> |
|
4400 |
<th align="left"> |
|
4401 |
the |
|
4402 |
<datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> |
|
4403 |
returned by <functionlink id="jvmtiHeapReferenceCallback"/> |
|
4404 |
</th> |
|
4405 |
<td> |
|
4406 |
<b>Yes</b> |
|
4407 |
</td> |
|
4408 |
<td> |
|
4409 |
<b>Yes</b>, since visits are controlled |
|
4410 |
</td> |
|
4411 |
<td> |
|
4412 |
<b>Yes</b>, since visits are controlled |
|
4413 |
</td> |
|
4414 |
</tr> |
|
4415 |
<tr> |
|
4416 |
<th align="left"> |
|
14287 | 4417 |
<fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
1 | 4418 |
in <paramlink id="callbacks"/> set |
4419 |
</th> |
|
4420 |
<td> |
|
4421 |
No |
|
4422 |
</td> |
|
4423 |
<td> |
|
4424 |
<b>Yes</b> |
|
4425 |
</td> |
|
4426 |
<td> |
|
4427 |
No |
|
4428 |
</td> |
|
4429 |
</tr> |
|
4430 |
<tr> |
|
4431 |
<th align="left"> |
|
4432 |
<paramlink id="heap_filter"/> |
|
4433 |
</th> |
|
4434 |
<td> |
|
4435 |
No |
|
4436 |
</td> |
|
4437 |
<td> |
|
4438 |
<b>Yes</b> |
|
4439 |
</td> |
|
4440 |
<td> |
|
4441 |
<b>Yes</b> |
|
4442 |
</td> |
|
4443 |
</tr> |
|
4444 |
<tr> |
|
4445 |
<th align="left"> |
|
4446 |
<paramlink id="klass"/> |
|
4447 |
</th> |
|
4448 |
<td> |
|
4449 |
No |
|
4450 |
</td> |
|
4451 |
<td> |
|
4452 |
<b>Yes</b> |
|
4453 |
</td> |
|
4454 |
<td> |
|
4455 |
<b>Yes</b> |
|
4456 |
</td> |
|
4457 |
</tr> |
|
4458 |
</table> |
|
4459 |
<p/> |
|
4460 |
During the execution of this function the state of the heap |
|
4461 |
does not change: no objects are allocated, no objects are |
|
4462 |
garbage collected, and the state of objects (including |
|
4463 |
held values) does not change. |
|
4464 |
As a result, threads executing Java |
|
4465 |
programming language code, threads attempting to resume the |
|
4466 |
execution of Java programming language code, and threads |
|
4467 |
attempting to execute JNI functions are typically stalled. |
|
4468 |
</description> |
|
4469 |
<origin>new</origin> |
|
4470 |
<capabilities> |
|
4471 |
<required id="can_tag_objects"></required> |
|
4472 |
</capabilities> |
|
4473 |
<parameters> |
|
4474 |
<param id="heap_filter"> |
|
4475 |
<jint/> |
|
4476 |
<description> |
|
4477 |
This bit vector of |
|
4478 |
<datalink id="jvmtiHeapFilter">heap filter flags</datalink>. |
|
4479 |
restricts the objects for which the callback function is called. |
|
4480 |
This applies to both the object and primitive callbacks. |
|
4481 |
</description> |
|
4482 |
</param> |
|
4483 |
<param id="klass"> |
|
4484 |
<ptrtype> |
|
4485 |
<jclass/> |
|
4486 |
<nullok>callbacks are not limited to instances of a particular |
|
4487 |
class</nullok> |
|
4488 |
</ptrtype> |
|
4489 |
<description> |
|
4490 |
Callbacks are only reported when the object is an instance of |
|
4491 |
this class. |
|
4492 |
Objects which are instances of a subclass of <code>klass</code> |
|
4493 |
are not reported. |
|
4494 |
If <code>klass</code> is an interface, no objects are reported. |
|
4495 |
This applies to both the object and primitive callbacks. |
|
4496 |
</description> |
|
4497 |
</param> |
|
4498 |
<param id="initial_object"> |
|
4499 |
<ptrtype> |
|
4500 |
<jobject/> |
|
4501 |
<nullok>references are followed from the heap roots</nullok> |
|
4502 |
</ptrtype> |
|
4503 |
<description> |
|
4504 |
The object to follow |
|
4505 |
</description> |
|
4506 |
</param> |
|
4507 |
<param id="callbacks"> |
|
4508 |
<inptr> |
|
4509 |
<struct>jvmtiHeapCallbacks</struct> |
|
4510 |
</inptr> |
|
4511 |
<description> |
|
4512 |
Structure defining the set of callback functions. |
|
4513 |
</description> |
|
4514 |
</param> |
|
4515 |
<param id="user_data"> |
|
4516 |
<inbuf> |
|
4517 |
<void/> |
|
4518 |
<nullok><code>NULL</code> is passed as the user supplied data</nullok> |
|
4519 |
</inbuf> |
|
4520 |
<description> |
|
4521 |
User supplied data to be passed to the callback. |
|
4522 |
</description> |
|
4523 |
</param> |
|
4524 |
</parameters> |
|
4525 |
<errors> |
|
4526 |
<error id="JVMTI_ERROR_INVALID_CLASS"> |
|
4527 |
<paramlink id="klass"/> is not a valid class. |
|
4528 |
</error> |
|
4529 |
<error id="JVMTI_ERROR_INVALID_OBJECT"> |
|
4530 |
<paramlink id="initial_object"/> is not a valid object. |
|
4531 |
</error> |
|
4532 |
</errors> |
|
4533 |
</function> |
|
4534 |
||
4535 |
||
4536 |
<function id="IterateThroughHeap" num="116" since="1.1"> |
|
4537 |
<synopsis>Iterate Through Heap</synopsis> |
|
4538 |
<description> |
|
4539 |
Initiate an iteration over all objects in the heap. |
|
4540 |
This includes both reachable and |
|
4541 |
unreachable objects. Objects are visited in no particular order. |
|
4542 |
<p/> |
|
4543 |
Heap objects are reported by invoking the agent supplied |
|
4544 |
callback function <functionlink id="jvmtiHeapIterationCallback"/>. |
|
4545 |
References between objects are not reported. |
|
4546 |
If only reachable objects are desired, or if object reference information |
|
4547 |
is needed, use <functionlink id="FollowReferences"/>. |
|
4548 |
<p/> |
|
4549 |
This function can also be used to examine primitive (non-object) values. |
|
4550 |
The primitive value of an array or String |
|
4551 |
is reported after the object has been visited; |
|
4552 |
it is reported by invoking the agent supplied callback function |
|
4553 |
<functionlink id="jvmtiArrayPrimitiveValueCallback"/> or |
|
4554 |
<functionlink id="jvmtiStringPrimitiveValueCallback"/>. |
|
4555 |
A primitive field |
|
4556 |
is reported after the object with that field is visited; |
|
4557 |
it is reported by invoking the agent supplied |
|
4558 |
callback function |
|
4559 |
<functionlink id="jvmtiPrimitiveFieldCallback"/>. |
|
4560 |
<p/> |
|
4561 |
Unless the iteration is aborted by the |
|
4562 |
<datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> |
|
4563 |
returned by a callback, all objects in the heap are visited. |
|
4564 |
Whether a callback is provided or is <code>NULL</code> only determines |
|
4565 |
whether the callback will be invoked, it does not influence |
|
4566 |
which objects are visited nor does it influence whether other callbacks |
|
4567 |
will be invoked. |
|
4568 |
The <datalink id="jvmtiHeapFilter">heap filter flags</datalink> |
|
4569 |
and <paramlink id="klass"/> provided as parameters to this function |
|
4570 |
do not control which objects are visited but they do control which |
|
4571 |
objects and primitive values are reported by the callbacks. |
|
4572 |
For example, if the only callback that was set is |
|
14287 | 4573 |
<fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code> |
1 | 4574 |
is set to the array of bytes class, then only arrays of byte will be |
4575 |
reported. The table below summarizes this (contrast this with |
|
4576 |
<functionlink id="FollowReferences"/>): |
|
4577 |
<p/> |
|
4578 |
<table> |
|
4579 |
<tr> |
|
4580 |
<th/> |
|
4581 |
<th> |
|
4582 |
Controls objects visited |
|
4583 |
</th> |
|
4584 |
<th> |
|
4585 |
Controls objects reported |
|
4586 |
</th> |
|
4587 |
<th> |
|
4588 |
Controls primitives reported |
|
4589 |
</th> |
|
4590 |
</tr> |
|
4591 |
<tr> |
|
4592 |
<th align="left"> |
|
4593 |
the |
|
4594 |
<datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink> |
|
4595 |
returned by <functionlink id="jvmtiHeapIterationCallback"/> |
|
4596 |
</th> |
|
4597 |
<td> |
|
4598 |
No<br/>(unless they abort the iteration) |
|
4599 |
</td> |
|
4600 |
<td> |
|
4601 |
No<br/>(unless they abort the iteration) |
|
4602 |
</td> |
|
4603 |
<td> |
|
4604 |
No<br/>(unless they abort the iteration) |
|
4605 |
</td> |
|
4606 |
</tr> |
|
4607 |
<tr> |
|
4608 |
<th align="left"> |
|
14287 | 4609 |
<fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> |
1 | 4610 |
in <paramlink id="callbacks"/> set |
4611 |
</th> |
|
4612 |
<td> |
|
4613 |
No |
|
4614 |
</td> |
|
4615 |
<td> |
|
4616 |
<b>Yes</b> |
|
4617 |
</td> |
|
4618 |
<td> |
|
4619 |
No |
|
4620 |
</td> |
|
4621 |
</tr> |
|
4622 |
<tr> |
|
4623 |
<th align="left"> |
|
4624 |
<paramlink id="heap_filter"/> |
|
4625 |
</th> |
|
4626 |
<td> |
|
4627 |
No |
|
4628 |
</td> |
|
4629 |
<td> |
|
4630 |
<b>Yes</b> |
|
4631 |
</td> |
|
4632 |
<td> |
|
4633 |
<b>Yes</b> |
|
4634 |
</td> |
|
4635 |
</tr> |
|
4636 |
<tr> |
|
4637 |
<th align="left"> |
|
4638 |
<paramlink id="klass"/> |
|
4639 |
</th> |
|
4640 |
<td> |
|
4641 |
No |
|
4642 |
</td> |
|
4643 |
<td> |
|
4644 |
<b>Yes</b> |
|
4645 |
</td> |
|
4646 |
<td> |
|
4647 |
<b>Yes</b> |
|
4648 |
</td> |
|
4649 |
</tr> |
|
4650 |
</table> |
|
4651 |
<p/> |
|
4652 |
During the execution of this function the state of the heap |
|
4653 |
does not change: no objects are allocated, no objects are |
|
4654 |
garbage collected, and the state of objects (including |
|
4655 |
held values) does not change. |
|
4656 |
As a result, threads executing Java |
|
4657 |
programming language code, threads attempting to resume the |
|
4658 |
execution of Java programming language code, and threads |
|
4659 |
attempting to execute JNI functions are typically stalled. |
|
4660 |
</description> |
|
4661 |
<origin>new</origin> |
|
4662 |
<capabilities> |
|
4663 |
<required id="can_tag_objects"></required> |
|
4664 |
</capabilities> |
|
4665 |
<parameters> |
|
4666 |
<param id="heap_filter"> |
|
4667 |
<jint/> |
|
4668 |
<description> |
|
4669 |
This bit vector of |
|
4670 |
<datalink id="jvmtiHeapFilter">heap filter flags</datalink>. |
|
4671 |
restricts the objects for which the callback function is called. |
|
4672 |
This applies to both the object and primitive callbacks. |
|
4673 |
</description> |
|
4674 |
</param> |
|
4675 |
<param id="klass"> |
|
4676 |
<ptrtype> |
|
4677 |
<jclass/> |
|
4678 |
<nullok>callbacks are not limited to instances of a particular class</nullok> |
|
4679 |
</ptrtype> |
|
4680 |
<description> |
|
4681 |
Callbacks are only reported when the object is an instance of |
|
4682 |
this class. |
|
4683 |
Objects which are instances of a subclass of <code>klass</code> |
|
4684 |
are not reported. |
|
4685 |
If <code>klass</code> is an interface, no objects are reported. |
|
4686 |
This applies to both the object and primitive callbacks. |
|
4687 |
</description> |
|
4688 |
</param> |
|
4689 |
<param id="callbacks"> |
|
4690 |
<inptr> |
|
4691 |
<struct>jvmtiHeapCallbacks</struct> |
|
4692 |
</inptr> |
|
4693 |
<description> |
|
4694 |
Structure defining the set callback functions. |
|
4695 |
</description> |
|
4696 |
</param> |
|
4697 |
<param id="user_data"> |
|
4698 |
<inbuf> |
|
4699 |
<void/> |
|
4700 |
<nullok><code>NULL</code> is passed as the user supplied data</nullok> |
|
4701 |
</inbuf> |
|
4702 |
<description> |
|
4703 |
User supplied data to be passed to the callback. |
|
4704 |
</description> |
|
4705 |
</param> |
|
4706 |
</parameters> |
|
4707 |
<errors> |
|
4708 |
<error id="JVMTI_ERROR_INVALID_CLASS"> |
|
4709 |
<paramlink id="klass"/> is not a valid class. |
|
4710 |
</error> |
|
4711 |
</errors> |
|
4712 |
</function> |
|
4713 |
||
4714 |
<function id="GetTag" phase="start" num="106"> |
|
4715 |
<synopsis>Get Tag</synopsis> |
|
4716 |
<description> |
|
4717 |
Retrieve the tag associated with an object. |
|
4718 |
The tag is a long value typically used to store a |
|
4719 |
unique identifier or pointer to object information. |
|
4720 |
The tag is set with |
|
4721 |
<functionlink id="SetTag"></functionlink>. |
|
4722 |
Objects for which no tags have been set return a |
|
4723 |
tag value of zero. |
|
4724 |
</description> |
|
4725 |
<origin>new</origin> |
|
4726 |
<capabilities> |
|
4727 |
<required id="can_tag_objects"></required> |
|
4728 |
</capabilities> |
|
4729 |
<parameters> |
|
4730 |
<param id="object"> |
|
4731 |
<jobject/> |
|
4732 |
<description> |
|
4733 |
The object whose tag is to be retrieved. |
|
4734 |
</description> |
|
4735 |
</param> |
|
4736 |
<param id="tag_ptr"> |
|
4737 |
<outptr><jlong/></outptr> |
|
4738 |
<description> |
|
4739 |
On return, the referenced long is set to the value |
|
4740 |
of the tag. |
|
4741 |
</description> |
|
4742 |
</param> |
|
4743 |
</parameters> |
|
4744 |
<errors> |
|
4745 |
</errors> |
|
4746 |
</function> |
|
4747 |
||
4748 |
<function id="SetTag" phase="start" num="107"> |
|
4749 |
<synopsis>Set Tag</synopsis> |
|
4750 |
<description> |
|
4751 |
Set the tag associated with an object. |
|
4752 |
The tag is a long value typically used to store a |
|
4753 |
unique identifier or pointer to object information. |
|
4754 |
The tag is visible with |
|
4755 |
<functionlink id="GetTag"></functionlink>. |
|
4756 |
</description> |
|
4757 |
<origin>new</origin> |
|
4758 |
<capabilities> |
|
4759 |
<required id="can_tag_objects"></required> |
|
4760 |
</capabilities> |
|
4761 |
<parameters> |
|
4762 |
<param id="object"> |
|
4763 |
<jobject/> |
|
4764 |
<description> |
|
4765 |
The object whose tag is to be set. |
|
4766 |
</description> |
|
4767 |
</param> |
|
4768 |
<param id="tag"> |
|
4769 |
<jlong/> |
|
4770 |
<description> |
|
4771 |
The new value of the tag. |
|
4772 |
</description> |
|
4773 |
</param> |
|
4774 |
</parameters> |
|
4775 |
<errors> |
|
4776 |
</errors> |
|
4777 |
</function> |
|
4778 |
||
4779 |
<function id="GetObjectsWithTags" num="114"> |
|
4780 |
<synopsis>Get Objects With Tags</synopsis> |
|
4781 |
<description> |
|
4782 |
Return objects in the heap with the specified tags. |
|
4783 |
The format is parallel arrays of objects and tags. |
|
4784 |
</description> |
|
4785 |
<origin>new</origin> |
|
4786 |
<capabilities> |
|
4787 |
<required id="can_tag_objects"></required> |
|
4788 |
</capabilities> |
|
4789 |
<parameters> |
|
4790 |
<param id="tag_count"> |
|
4791 |
<jint min="0"/> |
|
4792 |
<description> |
|
4793 |
Number of tags to scan for. |
|
4794 |
</description> |
|
4795 |
</param> |
|
4796 |
<param id="tags"> |
|
4797 |
<inbuf incount="tag_count"> |
|
4798 |
<jlong/> |
|
4799 |
</inbuf> |
|
4800 |
<description> |
|
4801 |
Scan for objects with these tags. |
|
4802 |
Zero is not permitted in this array. |
|
4803 |
</description> |
|
4804 |
</param> |
|
4805 |
<param id="count_ptr"> |
|
4806 |
<outptr> |
|
4807 |
<jint/> |
|
4808 |
</outptr> |
|
4809 |
<description> |
|
4810 |
Return the number of objects with any of the tags |
|
4811 |
in <paramlink id="tags"/>. |
|
4812 |
</description> |
|
4813 |
</param> |
|
4814 |
<param id="object_result_ptr"> |
|
4815 |
<allocbuf outcount="count_ptr"> |
|
4816 |
<jobject/> |
|
4817 |
<nullok>this information is not returned</nullok> |
|
4818 |
</allocbuf> |
|
4819 |
<description> |
|
4820 |
Returns the array of objects with any of the tags |
|
4821 |
in <paramlink id="tags"/>. |
|
4822 |
</description> |
|
4823 |
</param> |
|
4824 |
<param id="tag_result_ptr"> |
|
4825 |
<allocbuf outcount="count_ptr"> |
|
4826 |
<jlong/> |
|
4827 |
<nullok>this information is not returned</nullok> |
|
4828 |
</allocbuf> |
|
4829 |
<description> |
|
4830 |
For each object in <paramlink id="object_result_ptr"/>, |
|
4831 |
return the tag at the corresponding index. |
|
4832 |
</description> |
|
4833 |
</param> |
|
4834 |
</parameters> |
|
4835 |
<errors> |
|
4836 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
4837 |
Zero is present in <paramlink id="tags"></paramlink>. |
|
4838 |
</error> |
|
4839 |
</errors> |
|
4840 |
</function> |
|
4841 |
||
4842 |
<function id="ForceGarbageCollection" num="108"> |
|
4843 |
<synopsis>Force Garbage Collection</synopsis> |
|
4844 |
<description> |
|
4845 |
Force the VM to perform a garbage collection. |
|
4846 |
The garbage collection is as complete as possible. |
|
4847 |
This function does not cause finalizers to be run. |
|
4848 |
This function does not return until the garbage collection |
|
4849 |
is finished. |
|
4850 |
<p/> |
|
4851 |
Although garbage collection is as complete |
|
4852 |
as possible there is no guarantee that all |
|
4853 |
<eventlink id="ObjectFree"/> |
|
4854 |
events will have been |
|
4855 |
sent by the time that this function |
|
4856 |
returns. In particular, an object may be |
|
4857 |
prevented from being freed because it |
|
4858 |
is awaiting finalization. |
|
4859 |
</description> |
|
4860 |
<origin>new</origin> |
|
4861 |
<capabilities> |
|
4862 |
</capabilities> |
|
4863 |
<parameters> |
|
4864 |
</parameters> |
|
4865 |
<errors> |
|
4866 |
</errors> |
|
4867 |
</function> |
|
4868 |
||
4869 |
||
4870 |
</category> |
|
4871 |
||
4872 |
<category id="Heap_1_0" label="Heap (1.0)"> |
|
4873 |
<intro> |
|
4874 |
<b> |
|
4875 |
These functions and data types were introduced in the original |
|
4876 |
<jvmti/> version 1.0 and have been superseded by more |
|
4877 |
</b> |
|
4878 |
<internallink id="Heap"><b>powerful and flexible versions</b></internallink> |
|
4879 |
<b> |
|
4880 |
which: |
|
4881 |
</b> |
|
4882 |
<ul> |
|
4883 |
<li> |
|
4884 |
<b> |
|
4885 |
Allow access to primitive values (the value of Strings, arrays, |
|
4886 |
and primitive fields) |
|
4887 |
</b> |
|
4888 |
</li> |
|
4889 |
<li> |
|
4890 |
<b> |
|
4891 |
Allow the tag of the referrer to be set, thus enabling more |
|
4892 |
efficient localized reference graph building |
|
4893 |
</b> |
|
4894 |
</li> |
|
4895 |
<li> |
|
4896 |
<b> |
|
4897 |
Provide more extensive filtering abilities |
|
4898 |
</b> |
|
4899 |
</li> |
|
4900 |
<li> |
|
4901 |
<b> |
|
4902 |
Are extensible, allowing their abilities to grow in future versions of <jvmti/> |
|
4903 |
</b> |
|
4904 |
</li> |
|
4905 |
</ul> |
|
4906 |
<p/> |
|
4907 |
<b>Please use the </b> |
|
4908 |
<internallink id="Heap"><b>current Heap functions</b></internallink>. |
|
4909 |
<p/> |
|
4910 |
<constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum"> |
|
4911 |
<constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1"> |
|
4912 |
Tagged objects only. |
|
4913 |
</constant> |
|
4914 |
<constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2"> |
|
4915 |
Untagged objects only. |
|
4916 |
</constant> |
|
4917 |
<constant id="JVMTI_HEAP_OBJECT_EITHER" num="3"> |
|
4918 |
Either tagged or untagged objects. |
|
4919 |
</constant> |
|
4920 |
</constants> |
|
4921 |
||
4922 |
<constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum"> |
|
4923 |
<constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1"> |
|
4924 |
JNI global reference. |
|
4925 |
</constant> |
|
4926 |
<constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2"> |
|
4927 |
System class. |
|
4928 |
</constant> |
|
4929 |
<constant id="JVMTI_HEAP_ROOT_MONITOR" num="3"> |
|
4930 |
Monitor. |
|
4931 |
</constant> |
|
4932 |
<constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4"> |
|
4933 |
Stack local. |
|
4934 |
</constant> |
|
4935 |
<constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5"> |
|
4936 |
JNI local reference. |
|
4937 |
</constant> |
|
4938 |
<constant id="JVMTI_HEAP_ROOT_THREAD" num="6"> |
|
4939 |
Thread. |
|
4940 |
</constant> |
|
4941 |
<constant id="JVMTI_HEAP_ROOT_OTHER" num="7"> |
|
4942 |
Other. |
|
4943 |
</constant> |
|
4944 |
</constants> |
|
4945 |
||
4946 |
<constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum"> |
|
4947 |
<constant id="JVMTI_REFERENCE_CLASS" num="1"> |
|
4948 |
Reference from an object to its class. |
|
4949 |
</constant> |
|
4950 |
<constant id="JVMTI_REFERENCE_FIELD" num="2"> |
|
4951 |
Reference from an object to the value of one of its instance fields. |
|
4952 |
For references of this kind the <code>referrer_index</code> |
|
4953 |
parameter to the <internallink id="jvmtiObjectReferenceCallback"> |
|
4954 |
jvmtiObjectReferenceCallback</internallink> is the index of the |
|
4955 |
the instance field. The index is based on the order of all the |
|
4956 |
object's fields. This includes all fields of the directly declared |
|
4957 |
static and instance fields in the class, and includes all fields (both |
|
4958 |
public and private) fields declared in superclasses and superinterfaces. |
|
4959 |
The index is thus calculated by summing the index of the field in the directly |
|
4960 |
declared class (see <functionlink id="GetClassFields"/>), with the total |
|
4961 |
number of fields (both public and private) declared in all superclasses |
|
4962 |
and superinterfaces. The index starts at zero. |
|
4963 |
</constant> |
|
4964 |
<constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3"> |
|
4965 |
Reference from an array to one of its elements. |
|
4966 |
For references of this kind the <code>referrer_index</code> |
|
4967 |
parameter to the <internallink id="jvmtiObjectReferenceCallback"> |
|
4968 |
jvmtiObjectReferenceCallback</internallink> is the array index. |
|
4969 |
</constant> |
|
4970 |
<constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4"> |
|
4971 |
Reference from a class to its class loader. |
|
4972 |
</constant> |
|
4973 |
<constant id="JVMTI_REFERENCE_SIGNERS" num="5"> |
|
4974 |
Reference from a class to its signers array. |
|
4975 |
</constant> |
|
4976 |
<constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6"> |
|
4977 |
Reference from a class to its protection domain. |
|
4978 |
</constant> |
|
4979 |
<constant id="JVMTI_REFERENCE_INTERFACE" num="7"> |
|
4980 |
Reference from a class to one of its interfaces. |
|
4981 |
</constant> |
|
4982 |
<constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8"> |
|
4983 |
Reference from a class to the value of one of its static fields. |
|
4984 |
For references of this kind the <code>referrer_index</code> |
|
4985 |
parameter to the <internallink id="jvmtiObjectReferenceCallback"> |
|
4986 |
jvmtiObjectReferenceCallback</internallink> is the index of the |
|
4987 |
the static field. The index is based on the order of all the |
|
4988 |
object's fields. This includes all fields of the directly declared |
|
4989 |
static and instance fields in the class, and includes all fields (both |
|
4990 |
public and private) fields declared in superclasses and superinterfaces. |
|
4991 |
The index is thus calculated by summing the index of the field in the directly |
|
4992 |
declared class (see <functionlink id="GetClassFields"/>), with the total |
|
4993 |
number of fields (both public and private) declared in all superclasses |
|
4994 |
and superinterfaces. The index starts at zero. |
|
4995 |
Note: this definition differs from that in the <jvmti/> 1.0 Specification. |
|
4996 |
<rationale>No known implementations used the 1.0 definition.</rationale> |
|
4997 |
</constant> |
|
4998 |
<constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9"> |
|
4999 |
Reference from a class to a resolved entry in the constant pool. |
|
5000 |
For references of this kind the <code>referrer_index</code> |
|
5001 |
parameter to the <internallink id="jvmtiObjectReferenceCallback"> |
|
5002 |
jvmtiObjectReferenceCallback</internallink> is the index into |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
5003 |
constant pool table of the class, starting at 1. See |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
5004 |
<vmspec chapter="4.4"/>. |
1 | 5005 |
</constant> |
5006 |
</constants> |
|
5007 |
||
5008 |
<constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum"> |
|
5009 |
<constant id="JVMTI_ITERATION_CONTINUE" num="1"> |
|
5010 |
Continue the iteration. |
|
5011 |
If this is a reference iteration, follow the references of this object. |
|
5012 |
</constant> |
|
5013 |
<constant id="JVMTI_ITERATION_IGNORE" num="2"> |
|
5014 |
Continue the iteration. |
|
5015 |
If this is a reference iteration, ignore the references of this object. |
|
5016 |
</constant> |
|
5017 |
<constant id="JVMTI_ITERATION_ABORT" num="0"> |
|
5018 |
Abort the iteration. |
|
5019 |
</constant> |
|
5020 |
</constants> |
|
5021 |
</intro> |
|
5022 |
||
5023 |
<callback id="jvmtiHeapObjectCallback"> |
|
5024 |
<enum>jvmtiIterationControl</enum> |
|
5025 |
<synopsis>Heap Object Callback</synopsis> |
|
5026 |
<description> |
|
5027 |
Agent supplied callback function. |
|
5028 |
Describes (but does not pass in) an object in the heap. |
|
5029 |
<p/> |
|
5030 |
Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, |
|
5031 |
or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. |
|
5032 |
<p/> |
|
5033 |
See the <internallink id="heapCallbacks">heap callback |
|
5034 |
function restrictions</internallink>. |
|
5035 |
</description> |
|
5036 |
<parameters> |
|
5037 |
<param id="class_tag"> |
|
5038 |
<jlong/> |
|
5039 |
<description> |
|
5040 |
The tag of the class of object (zero if the class is not tagged). |
|
5041 |
If the object represents a runtime class, |
|
5042 |
the <code>class_tag</code> is the tag |
|
5043 |
associated with <code>java.lang.Class</code> |
|
5044 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
5045 |
</description> |
|
5046 |
</param> |
|
5047 |
<param id="size"> |
|
5048 |
<jlong/> |
|
5049 |
<description> |
|
5050 |
Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. |
|
5051 |
</description> |
|
5052 |
</param> |
|
5053 |
<param id="tag_ptr"> |
|
5054 |
<outptr><jlong/></outptr> |
|
5055 |
<description> |
|
5056 |
The object tag value, or zero if the object is not tagged. |
|
5057 |
To set the tag value to be associated with the object |
|
5058 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
5059 |
</description> |
|
5060 |
</param> |
|
5061 |
<param id="user_data"> |
|
5062 |
<outptr><void/></outptr> |
|
5063 |
<description> |
|
5064 |
The user supplied data that was passed into the iteration function. |
|
5065 |
</description> |
|
5066 |
</param> |
|
5067 |
</parameters> |
|
5068 |
</callback> |
|
5069 |
||
5070 |
<callback id="jvmtiHeapRootCallback"> |
|
5071 |
<enum>jvmtiIterationControl</enum> |
|
5072 |
<synopsis>Heap Root Object Callback</synopsis> |
|
5073 |
<description> |
|
5074 |
Agent supplied callback function. |
|
5075 |
Describes (but does not pass in) an object that is a root for the purposes |
|
5076 |
of garbage collection. |
|
5077 |
<p/> |
|
5078 |
Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, |
|
5079 |
<code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing |
|
5080 |
references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. |
|
5081 |
<p/> |
|
5082 |
See the <internallink id="heapCallbacks">heap callback |
|
5083 |
function restrictions</internallink>. |
|
5084 |
</description> |
|
5085 |
<parameters> |
|
5086 |
<param id="root_kind"> |
|
5087 |
<enum>jvmtiHeapRootKind</enum> |
|
5088 |
<description> |
|
5089 |
The kind of heap root. |
|
5090 |
</description> |
|
5091 |
</param> |
|
5092 |
<param id="class_tag"> |
|
5093 |
<jlong/> |
|
5094 |
<description> |
|
5095 |
The tag of the class of object (zero if the class is not tagged). |
|
5096 |
If the object represents a runtime class, the <code>class_tag</code> is the tag |
|
5097 |
associated with <code>java.lang.Class</code> |
|
5098 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
5099 |
</description> |
|
5100 |
</param> |
|
5101 |
<param id="size"> |
|
5102 |
<jlong/> |
|
5103 |
<description> |
|
5104 |
Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. |
|
5105 |
</description> |
|
5106 |
</param> |
|
5107 |
<param id="tag_ptr"> |
|
5108 |
<outptr><jlong/></outptr> |
|
5109 |
<description> |
|
5110 |
The object tag value, or zero if the object is not tagged. |
|
5111 |
To set the tag value to be associated with the object |
|
5112 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
5113 |
</description> |
|
5114 |
</param> |
|
5115 |
<param id="user_data"> |
|
5116 |
<outptr><void/></outptr> |
|
5117 |
<description> |
|
5118 |
The user supplied data that was passed into the iteration function. |
|
5119 |
</description> |
|
5120 |
</param> |
|
5121 |
</parameters> |
|
5122 |
</callback> |
|
5123 |
||
5124 |
<callback id="jvmtiStackReferenceCallback"> |
|
5125 |
<enum>jvmtiIterationControl</enum> |
|
5126 |
<synopsis>Stack Reference Object Callback</synopsis> |
|
5127 |
<description> |
|
5128 |
Agent supplied callback function. |
|
5129 |
Describes (but does not pass in) an object on the stack that is a root for |
|
5130 |
the purposes of garbage collection. |
|
5131 |
<p/> |
|
5132 |
Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, |
|
5133 |
<code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing |
|
5134 |
references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. |
|
5135 |
<p/> |
|
5136 |
See the <internallink id="heapCallbacks">heap callback |
|
5137 |
function restrictions</internallink>. |
|
5138 |
</description> |
|
5139 |
<parameters> |
|
5140 |
<param id="root_kind"> |
|
5141 |
<enum>jvmtiHeapRootKind</enum> |
|
5142 |
<description> |
|
5143 |
The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or |
|
5144 |
<code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>). |
|
5145 |
</description> |
|
5146 |
</param> |
|
5147 |
<param id="class_tag"> |
|
5148 |
<jlong/> |
|
5149 |
<description> |
|
5150 |
The tag of the class of object (zero if the class is not tagged). |
|
5151 |
If the object represents a runtime class, the <code>class_tag</code> is the tag |
|
5152 |
associated with <code>java.lang.Class</code> |
|
5153 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
5154 |
</description> |
|
5155 |
</param> |
|
5156 |
<param id="size"> |
|
5157 |
<jlong/> |
|
5158 |
<description> |
|
5159 |
Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. |
|
5160 |
</description> |
|
5161 |
</param> |
|
5162 |
<param id="tag_ptr"> |
|
5163 |
<outptr><jlong/></outptr> |
|
5164 |
<description> |
|
5165 |
The object tag value, or zero if the object is not tagged. |
|
5166 |
To set the tag value to be associated with the object |
|
5167 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
5168 |
</description> |
|
5169 |
</param> |
|
5170 |
<param id="thread_tag"> |
|
5171 |
<jlong/> |
|
5172 |
<description> |
|
5173 |
The tag of the thread corresponding to this stack, zero if not tagged. |
|
5174 |
</description> |
|
5175 |
</param> |
|
5176 |
<param id="depth"> |
|
5177 |
<jint/> |
|
5178 |
<description> |
|
5179 |
The depth of the frame. |
|
5180 |
</description> |
|
5181 |
</param> |
|
5182 |
<param id="method"> |
|
5183 |
<jmethodID/> |
|
5184 |
<description> |
|
5185 |
The method executing in this frame. |
|
5186 |
</description> |
|
5187 |
</param> |
|
5188 |
<param id="slot"> |
|
5189 |
<jint/> |
|
5190 |
<description> |
|
5191 |
The slot number. |
|
5192 |
</description> |
|
5193 |
</param> |
|
5194 |
<param id="user_data"> |
|
5195 |
<outptr><void/></outptr> |
|
5196 |
<description> |
|
5197 |
The user supplied data that was passed into the iteration function. |
|
5198 |
</description> |
|
5199 |
</param> |
|
5200 |
</parameters> |
|
5201 |
</callback> |
|
5202 |
||
5203 |
<callback id="jvmtiObjectReferenceCallback"> |
|
5204 |
<enum>jvmtiIterationControl</enum> |
|
5205 |
<synopsis>Object Reference Callback</synopsis> |
|
5206 |
<description> |
|
5207 |
Agent supplied callback function. |
|
5208 |
Describes a reference from an object (the referrer) to another object |
|
5209 |
(the referree). |
|
5210 |
<p/> |
|
5211 |
Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration, |
|
5212 |
<code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing |
|
5213 |
references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration. |
|
5214 |
<p/> |
|
5215 |
See the <internallink id="heapCallbacks">heap callback |
|
5216 |
function restrictions</internallink>. |
|
5217 |
</description> |
|
5218 |
<parameters> |
|
5219 |
<param id="reference_kind"> |
|
5220 |
<enum>jvmtiObjectReferenceKind</enum> |
|
5221 |
<description> |
|
5222 |
The type of reference. |
|
5223 |
</description> |
|
5224 |
</param> |
|
5225 |
<param id="class_tag"> |
|
5226 |
<jlong/> |
|
5227 |
<description> |
|
5228 |
The tag of the class of referree object (zero if the class is not tagged). |
|
5229 |
If the referree object represents a runtime class, |
|
5230 |
the <code>class_tag</code> is the tag |
|
5231 |
associated with <code>java.lang.Class</code> |
|
5232 |
(zero if <code>java.lang.Class</code> is not tagged). |
|
5233 |
</description> |
|
5234 |
</param> |
|
5235 |
<param id="size"> |
|
5236 |
<jlong/> |
|
5237 |
<description> |
|
5238 |
Size of the referree object (in bytes). |
|
5239 |
See <functionlink id="GetObjectSize"/>. |
|
5240 |
</description> |
|
5241 |
</param> |
|
5242 |
<param id="tag_ptr"> |
|
5243 |
<outptr><jlong/></outptr> |
|
5244 |
<description> |
|
5245 |
The referree object tag value, or zero if the object is not |
|
5246 |
tagged. |
|
5247 |
To set the tag value to be associated with the object |
|
5248 |
the agent sets the <code>jlong</code> pointed to by the parameter. |
|
5249 |
</description> |
|
5250 |
</param> |
|
5251 |
<param id="referrer_tag"> |
|
5252 |
<jlong/> |
|
5253 |
<description> |
|
5254 |
The tag of the referrer object, or zero if the referrer |
|
5255 |
object is not tagged. |
|
5256 |
</description> |
|
5257 |
</param> |
|
5258 |
<param id="referrer_index"> |
|
5259 |
<jint/> |
|
5260 |
<description> |
|
5261 |
For references of type <code>JVMTI_REFERENCE_FIELD</code> or |
|
5262 |
<code>JVMTI_REFERENCE_STATIC_FIELD</code> the index |
|
5263 |
of the field in the referrer object. The index is based on the |
|
5264 |
order of all the object's fields - see <internallink |
|
5265 |
id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink> |
|
5266 |
or <internallink |
|
5267 |
id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD |
|
5268 |
</internallink> for further description. |
|
5269 |
<p/> |
|
5270 |
For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code> |
|
5271 |
the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT"> |
|
5272 |
JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description. |
|
5273 |
<p/> |
|
5274 |
For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code> |
|
5275 |
the index into the constant pool of the class - see |
|
5276 |
<internallink id="JVMTI_REFERENCE_CONSTANT_POOL"> |
|
5277 |
JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further |
|
5278 |
description. |
|
5279 |
<p/> |
|
5280 |
For references of other kinds the <code>referrer_index</code> is |
|
5281 |
<code>-1</code>. |
|
5282 |
</description> |
|
5283 |
</param> |
|
5284 |
<param id="user_data"> |
|
5285 |
<outptr><void/></outptr> |
|
5286 |
<description> |
|
5287 |
The user supplied data that was passed into the iteration function. |
|
5288 |
</description> |
|
5289 |
</param> |
|
5290 |
</parameters> |
|
5291 |
</callback> |
|
5292 |
||
5293 |
<function id="IterateOverObjectsReachableFromObject" num="109"> |
|
5294 |
<synopsis>Iterate Over Objects Reachable From Object</synopsis> |
|
5295 |
<description> |
|
5296 |
This function iterates over all objects that are directly |
|
5297 |
and indirectly reachable from the specified object. |
|
5298 |
For each object <i>A</i> (known |
|
5299 |
as the referrer) with a reference to object <i>B</i> the specified |
|
5300 |
callback function is called to describe the object reference. |
|
5301 |
The callback is called exactly once for each reference from a referrer; |
|
5302 |
this is true even if there are reference cycles or multiple paths to |
|
5303 |
the referrer. |
|
5304 |
There may be more than one reference between a referrer and a referree, |
|
5305 |
These may be distinguished by the |
|
5306 |
<datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and |
|
5307 |
<datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. |
|
5308 |
The callback for an object will always occur after the callback for |
|
5309 |
its referrer. |
|
5310 |
<p/> |
|
5311 |
See <functionlink id="FollowReferences"/> for the object |
|
5312 |
references which are reported. |
|
5313 |
<p/> |
|
5314 |
During the execution of this function the state of the heap |
|
5315 |
does not change: no objects are allocated, no objects are |
|
5316 |
garbage collected, and the state of objects (including |
|
5317 |
held values) does not change. |
|
5318 |
As a result, threads executing Java |
|
5319 |
programming language code, threads attempting to resume the |
|
5320 |
execution of Java programming language code, and threads |
|
5321 |
attempting to execute JNI functions are typically stalled. |
|
5322 |
</description> |
|
5323 |
<origin>new</origin> |
|
5324 |
<capabilities> |
|
5325 |
<required id="can_tag_objects"></required> |
|
5326 |
</capabilities> |
|
5327 |
<parameters> |
|
5328 |
<param id="object"> |
|
5329 |
<jobject/> |
|
5330 |
<description> |
|
5331 |
The object |
|
5332 |
</description> |
|
5333 |
</param> |
|
5334 |
<param id="object_reference_callback"> |
|
5335 |
<ptrtype> |
|
5336 |
<struct>jvmtiObjectReferenceCallback</struct> |
|
5337 |
</ptrtype> |
|
5338 |
<description> |
|
5339 |
The callback to be called to describe each |
|
5340 |
object reference. |
|
5341 |
</description> |
|
5342 |
</param> |
|
5343 |
<param id="user_data"> |
|
5344 |
<inbuf> |
|
5345 |
<void/> |
|
5346 |
<nullok><code>NULL</code> is passed as the user supplied data</nullok> |
|
5347 |
</inbuf> |
|
5348 |
<description> |
|
5349 |
User supplied data to be passed to the callback. |
|
5350 |
</description> |
|
5351 |
</param> |
|
5352 |
</parameters> |
|
5353 |
<errors> |
|
5354 |
</errors> |
|
5355 |
</function> |
|
5356 |
||
5357 |
<function id="IterateOverReachableObjects" num="110"> |
|
5358 |
<synopsis>Iterate Over Reachable Objects</synopsis> |
|
5359 |
<description> |
|
5360 |
This function iterates over the root objects and all objects that |
|
5361 |
are directly and indirectly reachable from the root objects. |
|
5362 |
The root objects comprise the set of system classes, |
|
5363 |
JNI globals, references from thread stacks, and other objects used as roots |
|
5364 |
for the purposes of garbage collection. |
|
5365 |
<p/> |
|
5366 |
For each root the <paramlink id="heap_root_callback"></paramlink> |
|
5367 |
or <paramlink id="stack_ref_callback"></paramlink> callback is called. |
|
5368 |
An object can be a root object for more than one reason and in that case |
|
5369 |
the appropriate callback is called for each reason. |
|
5370 |
<p/> |
|
5371 |
For each object reference the <paramlink id="object_ref_callback"></paramlink> |
|
5372 |
callback function is called to describe the object reference. |
|
5373 |
The callback is called exactly once for each reference from a referrer; |
|
5374 |
this is true even if there are reference cycles or multiple paths to |
|
5375 |
the referrer. |
|
5376 |
There may be more than one reference between a referrer and a referree, |
|
5377 |
These may be distinguished by the |
|
5378 |
<datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and |
|
5379 |
<datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>. |
|
5380 |
The callback for an object will always occur after the callback for |
|
5381 |
its referrer. |
|
5382 |
<p/> |
|
5383 |
See <functionlink id="FollowReferences"/> for the object |
|
5384 |
references which are reported. |
|
5385 |
<p/> |
|
5386 |
Roots are always reported to the profiler before any object references |
|
5387 |
are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> |
|
5388 |
callback will not be called until the appropriate callback has been called |
|
5389 |
for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is |
|
5390 |
specified as <code>NULL</code> then this function returns after |
|
5391 |
reporting the root objects to the profiler. |
|
5392 |
<p/> |
|
5393 |
During the execution of this function the state of the heap |
|
5394 |
does not change: no objects are allocated, no objects are |
|
5395 |
garbage collected, and the state of objects (including |
|
5396 |
held values) does not change. |
|
5397 |
As a result, threads executing Java |
|
5398 |
programming language code, threads attempting to resume the |
|
5399 |
execution of Java programming language code, and threads |
|
5400 |
attempting to execute JNI functions are typically stalled. |
|
5401 |
</description> |
|
5402 |
<origin>new</origin> |
|
5403 |
<capabilities> |
|
5404 |
<required id="can_tag_objects"></required> |
|
5405 |
</capabilities> |
|
5406 |
<parameters> |
|
5407 |
<param id="heap_root_callback"> |
|
5408 |
<ptrtype> |
|
5409 |
<struct>jvmtiHeapRootCallback</struct> |
|
5410 |
<nullok>do not report heap roots</nullok> |
|
5411 |
</ptrtype> |
|
5412 |
<description> |
|
5413 |
The callback function to be called for each heap root of type |
|
5414 |
<code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>, |
|
5415 |
<code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>, |
|
5416 |
<code>JVMTI_HEAP_ROOT_MONITOR</code>, |
|
5417 |
<code>JVMTI_HEAP_ROOT_THREAD</code>, or |
|
5418 |
<code>JVMTI_HEAP_ROOT_OTHER</code>. |
|
5419 |
</description> |
|
5420 |
</param> |
|
5421 |
<param id="stack_ref_callback"> |
|
5422 |
<ptrtype> |
|
5423 |
<struct>jvmtiStackReferenceCallback</struct> |
|
5424 |
<nullok>do not report stack references</nullok> |
|
5425 |
</ptrtype> |
|
5426 |
<description> |
|
5427 |
The callback function to be called for each heap root of |
|
5428 |
<code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or |
|
5429 |
<code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>. |
|
5430 |
</description> |
|
5431 |
</param> |
|
5432 |
<param id="object_ref_callback"> |
|
5433 |
<ptrtype> |
|
5434 |
<struct>jvmtiObjectReferenceCallback</struct> |
|
5435 |
<nullok>do not follow references from the root objects</nullok> |
|
5436 |
</ptrtype> |
|
5437 |
<description> |
|
5438 |
The callback function to be called for each object reference. |
|
5439 |
</description> |
|
5440 |
</param> |
|
5441 |
<param id="user_data"> |
|
5442 |
<inbuf> |
|
5443 |
<void/> |
|
5444 |
<nullok><code>NULL</code> is passed as the user supplied data</nullok> |
|
5445 |
</inbuf> |
|
5446 |
<description> |
|
5447 |
User supplied data to be passed to the callback. |
|
5448 |
</description> |
|
5449 |
</param> |
|
5450 |
</parameters> |
|
5451 |
<errors> |
|
5452 |
</errors> |
|
5453 |
</function> |
|
5454 |
||
5455 |
<function id="IterateOverHeap" num="111"> |
|
5456 |
<synopsis>Iterate Over Heap</synopsis> |
|
5457 |
<description> |
|
5458 |
Iterate over all objects in the heap. This includes both reachable and |
|
5459 |
unreachable objects. |
|
5460 |
<p/> |
|
5461 |
The <paramlink id="object_filter"></paramlink> parameter indicates the |
|
5462 |
objects for which the callback function is called. If this parameter |
|
5463 |
is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be |
|
5464 |
called for every object that is tagged. If the parameter is |
|
5465 |
<code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be |
|
5466 |
for objects that are not tagged. If the parameter |
|
5467 |
is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be |
|
5468 |
called for every object in the heap, irrespective of whether it is |
|
5469 |
tagged or not. |
|
5470 |
<p/> |
|
5471 |
During the execution of this function the state of the heap |
|
5472 |
does not change: no objects are allocated, no objects are |
|
5473 |
garbage collected, and the state of objects (including |
|
5474 |
held values) does not change. |
|
5475 |
As a result, threads executing Java |
|
5476 |
programming language code, threads attempting to resume the |
|
5477 |
execution of Java programming language code, and threads |
|
5478 |
attempting to execute JNI functions are typically stalled. |
|
5479 |
</description> |
|
5480 |
<origin>new</origin> |
|
5481 |
<capabilities> |
|
5482 |
<required id="can_tag_objects"></required> |
|
5483 |
</capabilities> |
|
5484 |
<parameters> |
|
5485 |
<param id="object_filter"> |
|
5486 |
<enum>jvmtiHeapObjectFilter</enum> |
|
5487 |
<description> |
|
5488 |
Indicates the objects for which the callback function is called. |
|
5489 |
</description> |
|
5490 |
</param> |
|
5491 |
<param id="heap_object_callback"> |
|
5492 |
<ptrtype> |
|
5493 |
<struct>jvmtiHeapObjectCallback</struct> |
|
5494 |
</ptrtype> |
|
5495 |
<description> |
|
5496 |
The iterator function to be called for each |
|
5497 |
object matching the <paramlink id="object_filter"/>. |
|
5498 |
</description> |
|
5499 |
</param> |
|
5500 |
<param id="user_data"> |
|
5501 |
<inbuf> |
|
5502 |
<void/> |
|
5503 |
<nullok><code>NULL</code> is passed as the user supplied data</nullok> |
|
5504 |
</inbuf> |
|
5505 |
<description> |
|
5506 |
User supplied data to be passed to the callback. |
|
5507 |
</description> |
|
5508 |
</param> |
|
5509 |
</parameters> |
|
5510 |
<errors> |
|
5511 |
</errors> |
|
5512 |
</function> |
|
5513 |
||
5514 |
<function id="IterateOverInstancesOfClass" num="112"> |
|
5515 |
<synopsis>Iterate Over Instances Of Class</synopsis> |
|
5516 |
<description> |
|
5517 |
Iterate over all objects in the heap that are instances of the specified class. |
|
5518 |
This includes direct instances of the specified class and |
|
5519 |
instances of all subclasses of the specified class. |
|
5520 |
This includes both reachable and unreachable objects. |
|
5521 |
<p/> |
|
5522 |
The <paramlink id="object_filter"></paramlink> parameter indicates the |
|
5523 |
objects for which the callback function is called. If this parameter |
|
5524 |
is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be |
|
5525 |
called for every object that is tagged. If the parameter is |
|
5526 |
<code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be |
|
5527 |
called for objects that are not tagged. If the parameter |
|
5528 |
is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be |
|
5529 |
called for every object in the heap, irrespective of whether it is |
|
5530 |
tagged or not. |
|
5531 |
<p/> |
|
5532 |
During the execution of this function the state of the heap |
|
5533 |
does not change: no objects are allocated, no objects are |
|
5534 |
garbage collected, and the state of objects (including |
|
5535 |
held values) does not change. |
|
5536 |
As a result, threads executing Java |
|
5537 |
programming language code, threads attempting to resume the |
|
5538 |
execution of Java programming language code, and threads |
|
5539 |
attempting to execute JNI functions are typically stalled. |
|
5540 |
</description> |
|
5541 |
<origin>new</origin> |
|
5542 |
<capabilities> |
|
5543 |
<required id="can_tag_objects"></required> |
|
5544 |
</capabilities> |
|
5545 |
<parameters> |
|
5546 |
<param id="klass"> |
|
5547 |
<jclass/> |
|
5548 |
<description> |
|
5549 |
Iterate over objects of this class only. |
|
5550 |
</description> |
|
5551 |
</param> |
|
5552 |
<param id="object_filter"> |
|
5553 |
<enum>jvmtiHeapObjectFilter</enum> |
|
5554 |
<description> |
|
5555 |
Indicates the objects for which the callback function is called. |
|
5556 |
</description> |
|
5557 |
</param> |
|
5558 |
<param id="heap_object_callback"> |
|
5559 |
<ptrtype> |
|
5560 |
<struct>jvmtiHeapObjectCallback</struct> |
|
5561 |
</ptrtype> |
|
5562 |
<description> |
|
5563 |
The iterator function to be called for each |
|
5564 |
<paramlink id="klass"/> instance matching |
|
5565 |
the <paramlink id="object_filter"/>. |
|
5566 |
</description> |
|
5567 |
</param> |
|
5568 |
<param id="user_data"> |
|
5569 |
<inbuf> |
|
5570 |
<void/> |
|
5571 |
<nullok><code>NULL</code> is passed as the user supplied data</nullok> |
|
5572 |
</inbuf> |
|
5573 |
<description> |
|
5574 |
User supplied data to be passed to the callback. |
|
5575 |
</description> |
|
5576 |
</param> |
|
5577 |
</parameters> |
|
5578 |
<errors> |
|
5579 |
</errors> |
|
5580 |
</function> |
|
5581 |
||
5582 |
</category> |
|
5583 |
||
5584 |
<category id="local" label="Local Variable"> |
|
5585 |
||
5586 |
<intro> |
|
5587 |
These functions are used to retrieve or set the value of a local variable. |
|
5588 |
The variable is identified by the depth of the frame containing its |
|
5589 |
value and the variable's slot number within that frame. |
|
5590 |
The mapping of variables to |
|
5591 |
slot numbers can be obtained with the function |
|
5592 |
<functionlink id="GetLocalVariableTable"></functionlink>. |
|
5593 |
</intro> |
|
5594 |
||
5595 |
<function id="GetLocalObject" num="21"> |
|
5596 |
<synopsis>Get Local Variable - Object</synopsis> |
|
5597 |
<description> |
|
5598 |
This function can be used to retrieve the value of a local |
|
5599 |
variable whose type is <code>Object</code> or a subclass of <code>Object</code>. |
|
5600 |
</description> |
|
5601 |
<origin>jvmdi</origin> |
|
5602 |
<capabilities> |
|
5603 |
<required id="can_access_local_variables"></required> |
|
5604 |
</capabilities> |
|
5605 |
<parameters> |
|
5606 |
<param id="thread"> |
|
5607 |
<jthread null="current" frame="frame"/> |
|
5608 |
<description> |
|
5609 |
The thread of the frame containing the variable's value. |
|
5610 |
</description> |
|
5611 |
</param> |
|
5612 |
<param id="depth"> |
|
5613 |
<jframeID thread="thread"/> |
|
5614 |
<description> |
|
5615 |
The depth of the frame containing the variable's value. |
|
5616 |
</description> |
|
5617 |
</param> |
|
5618 |
<param id="slot"> |
|
5619 |
<jint/> |
|
5620 |
<description> |
|
5621 |
The variable's slot number. |
|
5622 |
</description> |
|
5623 |
</param> |
|
5624 |
<param id="value_ptr"> |
|
5625 |
<outptr><jobject/></outptr> |
|
5626 |
<description> |
|
5627 |
On return, points to the variable's value. |
|
5628 |
</description> |
|
5629 |
</param> |
|
5630 |
</parameters> |
|
5631 |
<errors> |
|
5632 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5633 |
Invalid <code>slot</code>. |
|
5634 |
</error> |
|
5635 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5636 |
The variable type is not |
|
5637 |
<code>Object</code> or a subclass of <code>Object</code>. |
|
5638 |
</error> |
|
5639 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5640 |
Not a visible frame |
|
5641 |
</error> |
|
5642 |
</errors> |
|
5643 |
</function> |
|
5644 |
||
7444 | 5645 |
<function id="GetLocalInstance" num="155" since="1.2"> |
5646 |
<synopsis>Get Local Instance</synopsis> |
|
5647 |
<description> |
|
5648 |
This function can be used to retrieve the value of the local object |
|
5649 |
variable at slot 0 (the "<code>this</code>" object) from non-static |
|
5650 |
frames. This function can retrieve the "<code>this</code>" object from |
|
5651 |
native method frames, whereas <code>GetLocalObject()</code> would |
|
5652 |
return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases. |
|
5653 |
</description> |
|
5654 |
<origin>new</origin> |
|
5655 |
<capabilities> |
|
5656 |
<required id="can_access_local_variables"></required> |
|
5657 |
</capabilities> |
|
5658 |
<parameters> |
|
5659 |
<param id="thread"> |
|
5660 |
<jthread null="current" frame="frame"/> |
|
5661 |
<description> |
|
5662 |
The thread of the frame containing the variable's value. |
|
5663 |
</description> |
|
5664 |
</param> |
|
5665 |
<param id="depth"> |
|
5666 |
<jframeID thread="thread"/> |
|
5667 |
<description> |
|
5668 |
The depth of the frame containing the variable's value. |
|
5669 |
</description> |
|
5670 |
</param> |
|
5671 |
<param id="value_ptr"> |
|
5672 |
<outptr><jobject/></outptr> |
|
5673 |
<description> |
|
5674 |
On return, points to the variable's value. |
|
5675 |
</description> |
|
5676 |
</param> |
|
5677 |
</parameters> |
|
5678 |
<errors> |
|
5679 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5680 |
If the specified frame is a static method frame. |
|
5681 |
</error> |
|
5682 |
</errors> |
|
5683 |
</function> |
|
1 | 5684 |
<function id="GetLocalInt" num="22"> |
5685 |
<synopsis>Get Local Variable - Int</synopsis> |
|
5686 |
<description> |
|
5687 |
This function can be used to retrieve the value of a local |
|
5688 |
variable whose type is <code>int</code>, |
|
5689 |
<code>short</code>, <code>char</code>, <code>byte</code>, or |
|
5690 |
<code>boolean</code>. |
|
5691 |
</description> |
|
5692 |
<origin>jvmdi</origin> |
|
5693 |
<capabilities> |
|
5694 |
<required id="can_access_local_variables"></required> |
|
5695 |
</capabilities> |
|
5696 |
<parameters> |
|
5697 |
<param id="thread"> |
|
5698 |
<jthread null="current" frame="frame"/> |
|
5699 |
<description> |
|
5700 |
The thread of the frame containing the variable's value. |
|
5701 |
</description> |
|
5702 |
</param> |
|
5703 |
<param id="depth"> |
|
5704 |
<jframeID thread="thread"/> |
|
5705 |
<description> |
|
5706 |
The depth of the frame containing the variable's value. |
|
5707 |
</description> |
|
5708 |
</param> |
|
5709 |
<param id="slot"> |
|
5710 |
<jint/> |
|
5711 |
<description> |
|
5712 |
The variable's slot number. |
|
5713 |
</description> |
|
5714 |
</param> |
|
5715 |
<param id="value_ptr"> |
|
5716 |
<outptr><jint/></outptr> |
|
5717 |
<description> |
|
5718 |
On return, points to the variable's value. |
|
5719 |
</description> |
|
5720 |
</param> |
|
5721 |
</parameters> |
|
5722 |
<errors> |
|
5723 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5724 |
Invalid <code>slot</code>. |
|
5725 |
</error> |
|
5726 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5727 |
The variable type is not |
|
5728 |
<code>int</code>, <code>short</code>, |
|
5729 |
<code>char</code>, <code>byte</code>, or |
|
5730 |
<code>boolean</code>. |
|
5731 |
</error> |
|
5732 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5733 |
Not a visible frame |
|
5734 |
</error> |
|
5735 |
</errors> |
|
5736 |
</function> |
|
5737 |
||
5738 |
<function id="GetLocalLong" num="23"> |
|
5739 |
<synopsis>Get Local Variable - Long</synopsis> |
|
5740 |
<description> |
|
5741 |
This function can be used to retrieve the value of a local |
|
5742 |
variable whose type is <code>long</code>. |
|
5743 |
</description> |
|
5744 |
<origin>jvmdi</origin> |
|
5745 |
<capabilities> |
|
5746 |
<required id="can_access_local_variables"></required> |
|
5747 |
</capabilities> |
|
5748 |
<parameters> |
|
5749 |
<param id="thread"> |
|
5750 |
<jthread null="current" frame="frame"/> |
|
5751 |
<description> |
|
5752 |
The thread of the frame containing the variable's value. |
|
5753 |
</description> |
|
5754 |
</param> |
|
5755 |
<param id="depth"> |
|
5756 |
<jframeID thread="thread"/> |
|
5757 |
<description> |
|
5758 |
The depth of the frame containing the variable's value. |
|
5759 |
</description> |
|
5760 |
</param> |
|
5761 |
<param id="slot"> |
|
5762 |
<jint/> |
|
5763 |
<description> |
|
5764 |
The variable's slot number. |
|
5765 |
</description> |
|
5766 |
</param> |
|
5767 |
<param id="value_ptr"> |
|
5768 |
<outptr><jlong/></outptr> |
|
5769 |
<description> |
|
5770 |
On return, points to the variable's value. |
|
5771 |
</description> |
|
5772 |
</param> |
|
5773 |
</parameters> |
|
5774 |
<errors> |
|
5775 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5776 |
Invalid <code>slot</code>. |
|
5777 |
</error> |
|
5778 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5779 |
The variable type is not <code>long</code>. |
|
5780 |
</error> |
|
5781 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5782 |
Not a visible frame |
|
5783 |
</error> |
|
5784 |
</errors> |
|
5785 |
</function> |
|
5786 |
||
5787 |
<function id="GetLocalFloat" num="24"> |
|
5788 |
<synopsis>Get Local Variable - Float</synopsis> |
|
5789 |
<description> |
|
5790 |
This function can be used to retrieve the value of a local |
|
5791 |
variable whose type is <code>float</code>. |
|
5792 |
</description> |
|
5793 |
<origin>jvmdi</origin> |
|
5794 |
<capabilities> |
|
5795 |
<required id="can_access_local_variables"></required> |
|
5796 |
</capabilities> |
|
5797 |
<parameters> |
|
5798 |
<param id="thread"> |
|
5799 |
<jthread null="current" frame="frame"/> |
|
5800 |
<description> |
|
5801 |
The thread of the frame containing the variable's value. |
|
5802 |
</description> |
|
5803 |
</param> |
|
5804 |
<param id="depth"> |
|
5805 |
<jframeID thread="thread"/> |
|
5806 |
<description> |
|
5807 |
The depth of the frame containing the variable's value. |
|
5808 |
</description> |
|
5809 |
</param> |
|
5810 |
<param id="slot"> |
|
5811 |
<jint/> |
|
5812 |
<description> |
|
5813 |
The variable's slot number. |
|
5814 |
</description> |
|
5815 |
</param> |
|
5816 |
<param id="value_ptr"> |
|
5817 |
<outptr><jfloat/></outptr> |
|
5818 |
<description> |
|
5819 |
On return, points to the variable's value. |
|
5820 |
</description> |
|
5821 |
</param> |
|
5822 |
</parameters> |
|
5823 |
<errors> |
|
5824 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5825 |
Invalid <code>slot</code>. |
|
5826 |
</error> |
|
5827 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5828 |
The variable type is not <code>float</code>. |
|
5829 |
</error> |
|
5830 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5831 |
Not a visible frame |
|
5832 |
</error> |
|
5833 |
</errors> |
|
5834 |
</function> |
|
5835 |
||
5836 |
<function id="GetLocalDouble" num="25"> |
|
5837 |
<synopsis>Get Local Variable - Double</synopsis> |
|
5838 |
<description> |
|
5839 |
This function can be used to retrieve the value of a local |
|
5840 |
variable whose type is <code>long</code>. |
|
5841 |
</description> |
|
5842 |
<origin>jvmdi</origin> |
|
5843 |
<capabilities> |
|
5844 |
<required id="can_access_local_variables"></required> |
|
5845 |
</capabilities> |
|
5846 |
<parameters> |
|
5847 |
<param id="thread"> |
|
5848 |
<jthread null="current" frame="frame"/> |
|
5849 |
<description> |
|
5850 |
The thread of the frame containing the variable's value. |
|
5851 |
</description> |
|
5852 |
</param> |
|
5853 |
<param id="depth"> |
|
5854 |
<jframeID thread="thread"/> |
|
5855 |
<description> |
|
5856 |
The depth of the frame containing the variable's value. |
|
5857 |
</description> |
|
5858 |
</param> |
|
5859 |
<param id="slot"> |
|
5860 |
<jint/> |
|
5861 |
<description> |
|
5862 |
The variable's slot number. |
|
5863 |
</description> |
|
5864 |
</param> |
|
5865 |
<param id="value_ptr"> |
|
5866 |
<outptr><jdouble/></outptr> |
|
5867 |
<description> |
|
5868 |
On return, points to the variable's value. |
|
5869 |
</description> |
|
5870 |
</param> |
|
5871 |
</parameters> |
|
5872 |
<errors> |
|
5873 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5874 |
Invalid <code>slot</code>. |
|
5875 |
</error> |
|
5876 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5877 |
The variable type is not <code>double</code>. |
|
5878 |
</error> |
|
5879 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5880 |
Not a visible frame |
|
5881 |
</error> |
|
5882 |
</errors> |
|
5883 |
</function> |
|
5884 |
||
5885 |
<function id="SetLocalObject" num="26"> |
|
5886 |
<synopsis>Set Local Variable - Object</synopsis> |
|
5887 |
<description> |
|
5888 |
This function can be used to set the value of a local |
|
5889 |
variable whose type is <code>Object</code> or a subclass of <code>Object</code>. |
|
5890 |
</description> |
|
5891 |
<origin>jvmdi</origin> |
|
5892 |
<capabilities> |
|
5893 |
<required id="can_access_local_variables"></required> |
|
5894 |
</capabilities> |
|
5895 |
<parameters> |
|
5896 |
<param id="thread"> |
|
5897 |
<jthread null="current" frame="frame"/> |
|
5898 |
<description> |
|
5899 |
The thread of the frame containing the variable's value. |
|
5900 |
</description> |
|
5901 |
</param> |
|
5902 |
<param id="depth"> |
|
5903 |
<jframeID thread="thread"/> |
|
5904 |
<description> |
|
5905 |
The depth of the frame containing the variable's value. |
|
5906 |
</description> |
|
5907 |
</param> |
|
5908 |
<param id="slot"> |
|
5909 |
<jint/> |
|
5910 |
<description> |
|
5911 |
The variable's slot number. |
|
5912 |
</description> |
|
5913 |
</param> |
|
5914 |
<param id="value"> |
|
5915 |
<jobject/> |
|
5916 |
<description> |
|
5917 |
The new value for the variable. |
|
5918 |
</description> |
|
5919 |
</param> |
|
5920 |
</parameters> |
|
5921 |
<errors> |
|
5922 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5923 |
Invalid <code>slot</code>. |
|
5924 |
</error> |
|
5925 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5926 |
The variable type is not |
|
5927 |
<code>Object</code> or a subclass of <code>Object</code>. |
|
5928 |
</error> |
|
5929 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5930 |
The supplied <paramlink id="value"/> is not compatible |
|
5931 |
with the variable type. |
|
5932 |
</error> |
|
5933 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5934 |
Not a visible frame |
|
5935 |
</error> |
|
5936 |
</errors> |
|
5937 |
</function> |
|
5938 |
||
5939 |
<function id="SetLocalInt" num="27"> |
|
5940 |
<synopsis>Set Local Variable - Int</synopsis> |
|
5941 |
<description> |
|
5942 |
This function can be used to set the value of a local |
|
5943 |
variable whose type is <code>int</code>, |
|
5944 |
<code>short</code>, <code>char</code>, <code>byte</code>, or |
|
5945 |
<code>boolean</code>. |
|
5946 |
</description> |
|
5947 |
<origin>jvmdi</origin> |
|
5948 |
<capabilities> |
|
5949 |
<required id="can_access_local_variables"></required> |
|
5950 |
</capabilities> |
|
5951 |
<parameters> |
|
5952 |
<param id="thread"> |
|
5953 |
<jthread null="current" frame="frame"/> |
|
5954 |
<description> |
|
5955 |
The thread of the frame containing the variable's value. |
|
5956 |
</description> |
|
5957 |
</param> |
|
5958 |
<param id="depth"> |
|
5959 |
<jframeID thread="thread"/> |
|
5960 |
<description> |
|
5961 |
The depth of the frame containing the variable's value. |
|
5962 |
</description> |
|
5963 |
</param> |
|
5964 |
<param id="slot"> |
|
5965 |
<jint/> |
|
5966 |
<description> |
|
5967 |
The variable's slot number. |
|
5968 |
</description> |
|
5969 |
</param> |
|
5970 |
<param id="value"> |
|
5971 |
<jint/> |
|
5972 |
<description> |
|
5973 |
The new value for the variable. |
|
5974 |
</description> |
|
5975 |
</param> |
|
5976 |
</parameters> |
|
5977 |
<errors> |
|
5978 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
5979 |
Invalid <code>slot</code>. |
|
5980 |
</error> |
|
5981 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
5982 |
The variable type is not |
|
5983 |
<code>int</code>, <code>short</code>, |
|
5984 |
<code>char</code>, <code>byte</code>, or |
|
5985 |
<code>boolean</code>. |
|
5986 |
</error> |
|
5987 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
5988 |
Not a visible frame |
|
5989 |
</error> |
|
5990 |
</errors> |
|
5991 |
</function> |
|
5992 |
||
5993 |
<function id="SetLocalLong" num="28"> |
|
5994 |
<synopsis>Set Local Variable - Long</synopsis> |
|
5995 |
<description> |
|
5996 |
This function can be used to set the value of a local |
|
5997 |
variable whose type is <code>long</code>. |
|
5998 |
</description> |
|
5999 |
<origin>jvmdi</origin> |
|
6000 |
<capabilities> |
|
6001 |
<required id="can_access_local_variables"></required> |
|
6002 |
</capabilities> |
|
6003 |
<parameters> |
|
6004 |
<param id="thread"> |
|
6005 |
<jthread null="current" frame="frame"/> |
|
6006 |
<description> |
|
6007 |
The thread of the frame containing the variable's value. |
|
6008 |
</description> |
|
6009 |
</param> |
|
6010 |
<param id="depth"> |
|
6011 |
<jframeID thread="thread"/> |
|
6012 |
<description> |
|
6013 |
The depth of the frame containing the variable's value. |
|
6014 |
</description> |
|
6015 |
</param> |
|
6016 |
<param id="slot"> |
|
6017 |
<jint/> |
|
6018 |
<description> |
|
6019 |
The variable's slot number. |
|
6020 |
</description> |
|
6021 |
</param> |
|
6022 |
<param id="value"> |
|
6023 |
<jlong/> |
|
6024 |
<description> |
|
6025 |
The new value for the variable. |
|
6026 |
</description> |
|
6027 |
</param> |
|
6028 |
</parameters> |
|
6029 |
<errors> |
|
6030 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
6031 |
Invalid <code>slot</code>. |
|
6032 |
</error> |
|
6033 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
6034 |
The variable type is not <code>long</code>. |
|
6035 |
</error> |
|
6036 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
6037 |
Not a visible frame |
|
6038 |
</error> |
|
6039 |
</errors> |
|
6040 |
</function> |
|
6041 |
||
6042 |
<function id="SetLocalFloat" num="29"> |
|
6043 |
<synopsis>Set Local Variable - Float</synopsis> |
|
6044 |
<description> |
|
6045 |
This function can be used to set the value of a local |
|
6046 |
variable whose type is <code>float</code>. |
|
6047 |
</description> |
|
6048 |
<origin>jvmdi</origin> |
|
6049 |
<capabilities> |
|
6050 |
<required id="can_access_local_variables"></required> |
|
6051 |
</capabilities> |
|
6052 |
<parameters> |
|
6053 |
<param id="thread"> |
|
6054 |
<jthread null="current" frame="frame"/> |
|
6055 |
<description> |
|
6056 |
The thread of the frame containing the variable's value. |
|
6057 |
</description> |
|
6058 |
</param> |
|
6059 |
<param id="depth"> |
|
6060 |
<jframeID thread="thread"/> |
|
6061 |
<description> |
|
6062 |
The depth of the frame containing the variable's value. |
|
6063 |
</description> |
|
6064 |
</param> |
|
6065 |
<param id="slot"> |
|
6066 |
<jint/> |
|
6067 |
<description> |
|
6068 |
The variable's slot number. |
|
6069 |
</description> |
|
6070 |
</param> |
|
6071 |
<param id="value"> |
|
6072 |
<jfloat/> |
|
6073 |
<description> |
|
6074 |
The new value for the variable. |
|
6075 |
</description> |
|
6076 |
</param> |
|
6077 |
</parameters> |
|
6078 |
<errors> |
|
6079 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
6080 |
Invalid <code>slot</code>. |
|
6081 |
</error> |
|
6082 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
6083 |
The variable type is not <code>float</code>. |
|
6084 |
</error> |
|
6085 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
6086 |
Not a visible frame |
|
6087 |
</error> |
|
6088 |
</errors> |
|
6089 |
</function> |
|
6090 |
||
6091 |
<function id="SetLocalDouble" num="30"> |
|
6092 |
<synopsis>Set Local Variable - Double</synopsis> |
|
6093 |
<description> |
|
6094 |
This function can be used to set the value of a local |
|
6095 |
variable whose type is <code>double</code>. |
|
6096 |
</description> |
|
6097 |
<origin>jvmdi</origin> |
|
6098 |
<capabilities> |
|
6099 |
<required id="can_access_local_variables"></required> |
|
6100 |
</capabilities> |
|
6101 |
<parameters> |
|
6102 |
<param id="thread"> |
|
6103 |
<jthread null="current" frame="frame"/> |
|
6104 |
<description> |
|
6105 |
The thread of the frame containing the variable's value. |
|
6106 |
</description> |
|
6107 |
</param> |
|
6108 |
<param id="depth"> |
|
6109 |
<jframeID thread="thread"/> |
|
6110 |
<description> |
|
6111 |
The depth of the frame containing the variable's value. |
|
6112 |
</description> |
|
6113 |
</param> |
|
6114 |
<param id="slot"> |
|
6115 |
<jint/> |
|
6116 |
<description> |
|
6117 |
The variable's slot number. |
|
6118 |
</description> |
|
6119 |
</param> |
|
6120 |
<param id="value"> |
|
6121 |
<jdouble/> |
|
6122 |
<description> |
|
6123 |
The new value for the variable. |
|
6124 |
</description> |
|
6125 |
</param> |
|
6126 |
</parameters> |
|
6127 |
<errors> |
|
6128 |
<error id="JVMTI_ERROR_INVALID_SLOT"> |
|
6129 |
Invalid <code>slot</code>. |
|
6130 |
</error> |
|
6131 |
<error id="JVMTI_ERROR_TYPE_MISMATCH"> |
|
6132 |
The variable type is not <code>double</code>. |
|
6133 |
</error> |
|
6134 |
<error id="JVMTI_ERROR_OPAQUE_FRAME"> |
|
6135 |
Not a visible frame |
|
6136 |
</error> |
|
6137 |
</errors> |
|
6138 |
</function> |
|
6139 |
</category> |
|
6140 |
||
6141 |
<category id="breakpointCategory" label="Breakpoint"> |
|
6142 |
||
6143 |
<intro> |
|
6144 |
</intro> |
|
6145 |
||
6146 |
<function id="SetBreakpoint" num="38"> |
|
6147 |
<synopsis>Set Breakpoint</synopsis> |
|
6148 |
<description> |
|
6149 |
Set a breakpoint at the instruction indicated by |
|
6150 |
<code>method</code> and <code>location</code>. |
|
6151 |
An instruction can only have one breakpoint. |
|
6152 |
<p/> |
|
6153 |
Whenever the designated instruction is about to be executed, a |
|
6154 |
<eventlink id="Breakpoint"></eventlink> event is generated. |
|
6155 |
</description> |
|
6156 |
<origin>jvmdi</origin> |
|
6157 |
<capabilities> |
|
6158 |
<required id="can_generate_breakpoint_events"></required> |
|
6159 |
</capabilities> |
|
6160 |
<parameters> |
|
6161 |
<param id="klass"> |
|
6162 |
<jclass method="method"/> |
|
6163 |
<description> |
|
6164 |
The class in which to set the breakpoint |
|
6165 |
</description> |
|
6166 |
</param> |
|
6167 |
<param id="method"> |
|
6168 |
<jmethodID class="klass"/> |
|
6169 |
<description> |
|
6170 |
The method in which to set the breakpoint |
|
6171 |
</description> |
|
6172 |
</param> |
|
6173 |
<param id="location"> |
|
6174 |
<jlocation/> |
|
6175 |
<description> |
|
6176 |
the index of the instruction at which to set the breakpoint |
|
6177 |
||
6178 |
</description> |
|
6179 |
</param> |
|
6180 |
</parameters> |
|
6181 |
<errors> |
|
6182 |
<error id="JVMTI_ERROR_DUPLICATE"> |
|
6183 |
The designated bytecode already has a breakpoint. |
|
6184 |
</error> |
|
6185 |
</errors> |
|
6186 |
</function> |
|
6187 |
||
6188 |
<function id="ClearBreakpoint" num="39"> |
|
6189 |
<synopsis>Clear Breakpoint</synopsis> |
|
6190 |
<description> |
|
6191 |
Clear the breakpoint at the bytecode indicated by |
|
6192 |
<code>method</code> and <code>location</code>. |
|
6193 |
</description> |
|
6194 |
<origin>jvmdi</origin> |
|
6195 |
<capabilities> |
|
6196 |
<required id="can_generate_breakpoint_events"></required> |
|
6197 |
</capabilities> |
|
6198 |
<parameters> |
|
6199 |
<param id="klass"> |
|
6200 |
<jclass method="method"/> |
|
6201 |
<description> |
|
6202 |
The class in which to clear the breakpoint |
|
6203 |
</description> |
|
6204 |
</param> |
|
6205 |
<param id="method"> |
|
6206 |
<jmethodID class="klass"/> |
|
6207 |
<description> |
|
6208 |
The method in which to clear the breakpoint |
|
6209 |
</description> |
|
6210 |
</param> |
|
6211 |
<param id="location"> |
|
6212 |
<jlocation/> |
|
6213 |
<description> |
|
6214 |
the index of the instruction at which to clear the breakpoint |
|
6215 |
</description> |
|
6216 |
</param> |
|
6217 |
</parameters> |
|
6218 |
<errors> |
|
6219 |
<error id="JVMTI_ERROR_NOT_FOUND"> |
|
6220 |
There's no breakpoint at the designated bytecode. |
|
6221 |
</error> |
|
6222 |
</errors> |
|
6223 |
</function> |
|
6224 |
||
6225 |
</category> |
|
6226 |
||
6227 |
<category id="fieldWatch" label="Watched Field"> |
|
6228 |
||
6229 |
<intro> |
|
6230 |
</intro> |
|
6231 |
||
6232 |
<function id="SetFieldAccessWatch" num="41"> |
|
6233 |
<synopsis>Set Field Access Watch</synopsis> |
|
6234 |
<description> |
|
6235 |
Generate a <eventlink id="FieldAccess"></eventlink> event |
|
6236 |
when the field specified |
|
6237 |
by <code>klass</code> and |
|
6238 |
<code>field</code> is about to be accessed. |
|
6239 |
An event will be generated for each access of the field |
|
6240 |
until it is canceled with |
|
6241 |
<functionlink id="ClearFieldAccessWatch"></functionlink>. |
|
6242 |
Field accesses from Java programming language code or from JNI code are watched, |
|
6243 |
fields modified by other means are not watched. |
|
6244 |
Note that <jvmti/> users should be aware that their own field accesses |
|
6245 |
will trigger the watch. |
|
6246 |
A field can only have one field access watch set. |
|
6247 |
Modification of a field is not considered an access--use |
|
6248 |
<functionlink id="SetFieldModificationWatch"></functionlink> |
|
6249 |
to monitor modifications. |
|
6250 |
</description> |
|
6251 |
<origin>jvmdi</origin> |
|
6252 |
<capabilities> |
|
6253 |
<required id="can_generate_field_access_events"></required> |
|
6254 |
</capabilities> |
|
6255 |
<parameters> |
|
6256 |
<param id="klass"> |
|
6257 |
<jclass field="field"/> |
|
6258 |
<description> |
|
6259 |
The class containing the field to watch |
|
6260 |
</description> |
|
6261 |
</param> |
|
6262 |
<param id="field"> |
|
6263 |
<jfieldID class="klass"/> |
|
6264 |
<description> |
|
6265 |
The field to watch |
|
6266 |
||
6267 |
</description> |
|
6268 |
</param> |
|
6269 |
</parameters> |
|
6270 |
<errors> |
|
6271 |
<error id="JVMTI_ERROR_DUPLICATE"> |
|
6272 |
The designated field is already being watched for accesses. |
|
6273 |
</error> |
|
6274 |
</errors> |
|
6275 |
</function> |
|
6276 |
||
6277 |
<function id="ClearFieldAccessWatch" num="42"> |
|
6278 |
<synopsis>Clear Field Access Watch</synopsis> |
|
6279 |
<description> |
|
6280 |
Cancel a field access watch previously set by |
|
6281 |
<functionlink id="SetFieldAccessWatch"></functionlink>, on the |
|
6282 |
field specified |
|
6283 |
by <code>klass</code> and |
|
6284 |
<code>field</code>. |
|
6285 |
</description> |
|
6286 |
<origin>jvmdi</origin> |
|
6287 |
<capabilities> |
|
6288 |
<required id="can_generate_field_access_events"></required> |
|
6289 |
</capabilities> |
|
6290 |
<parameters> |
|
6291 |
<param id="klass"> |
|
6292 |
<jclass field="field"/> |
|
6293 |
<description> |
|
6294 |
The class containing the field to watch |
|
6295 |
</description> |
|
6296 |
</param> |
|
6297 |
<param id="field"> |
|
6298 |
<jfieldID class="klass"/> |
|
6299 |
<description> |
|
6300 |
The field to watch |
|
6301 |
||
6302 |
</description> |
|
6303 |
</param> |
|
6304 |
</parameters> |
|
6305 |
<errors> |
|
6306 |
<error id="JVMTI_ERROR_NOT_FOUND"> |
|
6307 |
The designated field is not being watched for accesses. |
|
6308 |
</error> |
|
6309 |
</errors> |
|
6310 |
</function> |
|
6311 |
||
6312 |
<function id="SetFieldModificationWatch" num="43"> |
|
6313 |
<synopsis>Set Field Modification Watch</synopsis> |
|
6314 |
<description> |
|
6315 |
Generate a <eventlink id="FieldModification"></eventlink> event |
|
6316 |
when the field specified |
|
6317 |
by <code>klass</code> and |
|
6318 |
<code>field</code> is about to be modified. |
|
6319 |
An event will be generated for each modification of the field |
|
6320 |
until it is canceled with |
|
6321 |
<functionlink id="ClearFieldModificationWatch"></functionlink>. |
|
6322 |
Field modifications from Java programming language code or from JNI code are watched, |
|
6323 |
fields modified by other means are not watched. |
|
6324 |
Note that <jvmti/> users should be aware that their own field modifications |
|
6325 |
will trigger the watch. |
|
6326 |
A field can only have one field modification watch set. |
|
6327 |
</description> |
|
6328 |
<origin>jvmdi</origin> |
|
6329 |
<capabilities> |
|
6330 |
<required id="can_generate_field_modification_events"></required> |
|
6331 |
</capabilities> |
|
6332 |
<parameters> |
|
6333 |
<param id="klass"> |
|
6334 |
<jclass field="field"/> |
|
6335 |
<description> |
|
6336 |
The class containing the field to watch |
|
6337 |
</description> |
|
6338 |
</param> |
|
6339 |
<param id="field"> |
|
6340 |
<jfieldID class="klass"/> |
|
6341 |
<description> |
|
6342 |
The field to watch |
|
6343 |
||
6344 |
</description> |
|
6345 |
</param> |
|
6346 |
</parameters> |
|
6347 |
<errors> |
|
6348 |
<error id="JVMTI_ERROR_DUPLICATE"> |
|
6349 |
The designated field is already being watched for modifications. |
|
6350 |
</error> |
|
6351 |
</errors> |
|
6352 |
</function> |
|
6353 |
||
6354 |
<function id="ClearFieldModificationWatch" num="44"> |
|
6355 |
<synopsis>Clear Field Modification Watch</synopsis> |
|
6356 |
<description> |
|
6357 |
||
6358 |
Cancel a field modification watch previously set by |
|
6359 |
<functionlink id="SetFieldModificationWatch"></functionlink>, on the |
|
6360 |
field specified |
|
6361 |
by <code>klass</code> and |
|
6362 |
<code>field</code>. |
|
6363 |
</description> |
|
6364 |
<origin>jvmdi</origin> |
|
6365 |
<capabilities> |
|
6366 |
<required id="can_generate_field_modification_events"></required> |
|
6367 |
</capabilities> |
|
6368 |
<parameters> |
|
6369 |
<param id="klass"> |
|
6370 |
<jclass field="field"/> |
|
6371 |
<description> |
|
6372 |
The class containing the field to watch |
|
6373 |
</description> |
|
6374 |
</param> |
|
6375 |
<param id="field"> |
|
6376 |
<jfieldID class="klass"/> |
|
6377 |
<description> |
|
6378 |
The field to watch |
|
6379 |
||
6380 |
</description> |
|
6381 |
</param> |
|
6382 |
</parameters> |
|
6383 |
<errors> |
|
6384 |
<error id="JVMTI_ERROR_NOT_FOUND"> |
|
6385 |
The designated field is not being watched for modifications. |
|
6386 |
</error> |
|
6387 |
</errors> |
|
6388 |
</function> |
|
6389 |
</category> |
|
6390 |
||
6391 |
<category id="class" label="Class"> |
|
6392 |
||
6393 |
<intro> |
|
6394 |
</intro> |
|
6395 |
||
6396 |
<function id="GetLoadedClasses" jkernel="yes" num="78"> |
|
6397 |
<synopsis>Get Loaded Classes</synopsis> |
|
6398 |
<description> |
|
6399 |
Return an array of all classes loaded in the virtual machine. |
|
6400 |
The number of classes in the array is returned via |
|
6401 |
<code>class_count_ptr</code>, and the array itself via |
|
6402 |
<code>classes_ptr</code>. |
|
6403 |
<p/> |
|
6404 |
Array classes of all types (including arrays of primitive types) are |
|
6405 |
included in the returned list. Primitive classes (for example, |
|
6406 |
<code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. |
|
6407 |
</description> |
|
6408 |
<origin>jvmdi</origin> |
|
6409 |
<capabilities> |
|
6410 |
</capabilities> |
|
6411 |
<parameters> |
|
6412 |
<param id="class_count_ptr"> |
|
6413 |
<outptr><jint/></outptr> |
|
6414 |
<description> |
|
6415 |
On return, points to the number of classes. |
|
6416 |
</description> |
|
6417 |
</param> |
|
6418 |
<param id="classes_ptr"> |
|
6419 |
<allocbuf outcount="class_count_ptr"><jclass/></allocbuf> |
|
6420 |
<description> |
|
6421 |
On return, points to an array of references, one |
|
6422 |
for each class. |
|
6423 |
</description> |
|
6424 |
</param> |
|
6425 |
</parameters> |
|
6426 |
<errors> |
|
6427 |
</errors> |
|
6428 |
</function> |
|
6429 |
||
6430 |
<function id="GetClassLoaderClasses" jkernel="yes" num="79"> |
|
6431 |
<synopsis>Get Classloader Classes</synopsis> |
|
6432 |
<description> |
|
6433 |
Returns an array of those classes for which this class loader has |
|
6434 |
been recorded as an initiating loader. Each |
|
6435 |
class in the returned array was created by this class loader, |
|
6436 |
either by defining it directly or by delegation to another class loader. |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
6437 |
See <vmspec chapter="5.3"/>. |
1 | 6438 |
<p/> |
6439 |
For JDK version 1.1 implementations that don't |
|
6440 |
recognize the distinction between initiating and defining class loaders, |
|
6441 |
this function should return all classes loaded in the virtual machine. |
|
6442 |
The number of classes in the array is returned via |
|
6443 |
<code>class_count_ptr</code>, and the array itself via |
|
6444 |
<code>classes_ptr</code>. |
|
6445 |
</description> |
|
6446 |
<origin>jvmdi</origin> |
|
6447 |
<capabilities> |
|
6448 |
</capabilities> |
|
6449 |
<parameters> |
|
6450 |
<param id="initiating_loader"> |
|
6451 |
<ptrtype> |
|
6452 |
<jobject/> |
|
6453 |
<nullok>the classes initiated by the bootstrap loader will be returned</nullok> |
|
6454 |
</ptrtype> |
|
6455 |
<description> |
|
6456 |
An initiating class loader. |
|
6457 |
</description> |
|
6458 |
</param> |
|
6459 |
<param id="class_count_ptr"> |
|
6460 |
<outptr><jint/></outptr> |
|
6461 |
<description> |
|
6462 |
On return, points to the number of classes. |
|
6463 |
</description> |
|
6464 |
</param> |
|
6465 |
<param id="classes_ptr"> |
|
6466 |
<allocbuf outcount="class_count_ptr"><jclass/></allocbuf> |
|
6467 |
<description> |
|
6468 |
On return, points to an array of references, one |
|
6469 |
for each class. |
|
6470 |
</description> |
|
6471 |
</param> |
|
6472 |
</parameters> |
|
6473 |
<errors> |
|
6474 |
</errors> |
|
6475 |
</function> |
|
6476 |
||
6477 |
<function id="GetClassSignature" phase="start" num="48"> |
|
6478 |
<synopsis>Get Class Signature</synopsis> |
|
6479 |
<description> |
|
6480 |
For the class indicated by <code>klass</code>, return the |
|
14287 | 6481 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI |
1 | 6482 |
type signature</externallink> |
6483 |
and the generic signature of the class. |
|
6484 |
For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code> |
|
6485 |
and <code>int[]</code> is <code>"[I"</code> |
|
6486 |
The returned name for primitive classes |
|
6487 |
is the type signature character of the corresponding primitive type. |
|
6488 |
For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>. |
|
6489 |
</description> |
|
6490 |
<origin>jvmdiClone</origin> |
|
6491 |
<capabilities> |
|
6492 |
</capabilities> |
|
6493 |
<parameters> |
|
6494 |
<param id="klass"> |
|
6495 |
<jclass/> |
|
6496 |
<description> |
|
6497 |
The class to query. |
|
6498 |
</description> |
|
6499 |
</param> |
|
6500 |
<param id="signature_ptr"> |
|
6501 |
<allocbuf> |
|
6502 |
<char/> |
|
6503 |
<nullok>the signature is not returned</nullok> |
|
6504 |
</allocbuf> |
|
6505 |
<description> |
|
6506 |
On return, points to the JNI type signature of the class, encoded as a |
|
6507 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
6508 |
</description> |
|
6509 |
</param> |
|
6510 |
<param id="generic_ptr"> |
|
6511 |
<allocbuf> |
|
6512 |
<char/> |
|
6513 |
<nullok>the generic signature is not returned</nullok> |
|
6514 |
</allocbuf> |
|
6515 |
<description> |
|
6516 |
On return, points to the generic signature of the class, encoded as a |
|
6517 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
6518 |
If there is no generic signature attribute for the class, then, |
|
6519 |
on return, points to <code>NULL</code>. |
|
6520 |
</description> |
|
6521 |
</param> |
|
6522 |
</parameters> |
|
6523 |
<errors> |
|
6524 |
</errors> |
|
6525 |
</function> |
|
6526 |
||
6527 |
<function id="GetClassStatus" phase="start" num="49"> |
|
6528 |
<synopsis>Get Class Status</synopsis> |
|
6529 |
<description> |
|
6530 |
Get the status of the class. Zero or more of the following bits can be |
|
6531 |
set. |
|
6532 |
<constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits"> |
|
6533 |
<constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1"> |
|
6534 |
Class bytecodes have been verified |
|
6535 |
</constant> |
|
6536 |
<constant id="JVMTI_CLASS_STATUS_PREPARED" num="2"> |
|
6537 |
Class preparation is complete |
|
6538 |
</constant> |
|
6539 |
<constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4"> |
|
6540 |
Class initialization is complete. Static initializer has been run. |
|
6541 |
</constant> |
|
6542 |
<constant id="JVMTI_CLASS_STATUS_ERROR" num="8"> |
|
6543 |
Error during initialization makes class unusable |
|
6544 |
</constant> |
|
6545 |
<constant id="JVMTI_CLASS_STATUS_ARRAY" num="16"> |
|
6546 |
Class is an array. If set, all other bits are zero. |
|
6547 |
</constant> |
|
6548 |
<constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32"> |
|
6549 |
Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>). |
|
6550 |
If set, all other bits are zero. |
|
6551 |
</constant> |
|
6552 |
</constants> |
|
6553 |
</description> |
|
6554 |
<origin>jvmdi</origin> |
|
6555 |
<capabilities> |
|
6556 |
</capabilities> |
|
6557 |
<parameters> |
|
6558 |
<param id="klass"> |
|
6559 |
<jclass/> |
|
6560 |
<description> |
|
6561 |
The class to query. |
|
6562 |
</description> |
|
6563 |
</param> |
|
6564 |
<param id="status_ptr"> |
|
6565 |
<outptr><jint/></outptr> |
|
6566 |
<description> |
|
6567 |
On return, points to the current state of this class as one or |
|
6568 |
more of the <internallink id="jvmtiClassStatus">class status flags</internallink>. |
|
6569 |
</description> |
|
6570 |
</param> |
|
6571 |
</parameters> |
|
6572 |
<errors> |
|
6573 |
</errors> |
|
6574 |
</function> |
|
6575 |
||
6576 |
<function id="GetSourceFileName" phase="start" num="50"> |
|
6577 |
<synopsis>Get Source File Name</synopsis> |
|
6578 |
<description> |
|
6579 |
For the class indicated by <code>klass</code>, return the source file |
|
6580 |
name via <code>source_name_ptr</code>. The returned string |
|
6581 |
is a file name only and never contains a directory name. |
|
6582 |
<p/> |
|
6583 |
For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) |
|
6584 |
and for arrays this function returns |
|
6585 |
<errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>. |
|
6586 |
</description> |
|
6587 |
<origin>jvmdi</origin> |
|
6588 |
<capabilities> |
|
6589 |
<required id="can_get_source_file_name"></required> |
|
6590 |
</capabilities> |
|
6591 |
<parameters> |
|
6592 |
<param id="klass"> |
|
6593 |
<jclass/> |
|
6594 |
<description> |
|
6595 |
The class to query. |
|
6596 |
</description> |
|
6597 |
</param> |
|
6598 |
<param id="source_name_ptr"> |
|
6599 |
<allocbuf><char/></allocbuf> |
|
6600 |
<description> |
|
6601 |
On return, points to the class's source file name, encoded as a |
|
6602 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
6603 |
</description> |
|
6604 |
</param> |
|
6605 |
</parameters> |
|
6606 |
<errors> |
|
6607 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
6608 |
Class information does not include a source file name. This includes |
|
6609 |
cases where the class is an array class or primitive class. |
|
6610 |
</error> |
|
6611 |
</errors> |
|
6612 |
</function> |
|
6613 |
||
6614 |
<function id="GetClassModifiers" phase="start" num="51"> |
|
6615 |
<synopsis>Get Class Modifiers</synopsis> |
|
6616 |
<description> |
|
6617 |
For the class indicated by <code>klass</code>, return the access |
|
6618 |
flags |
|
6619 |
via <code>modifiers_ptr</code>. |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
6620 |
Access flags are defined in <vmspec chapter="4"/>. |
1 | 6621 |
<p/> |
6622 |
If the class is an array class, then its public, private, and protected |
|
6623 |
modifiers are the same as those of its component type. For arrays of |
|
6624 |
primitives, this component type is represented by one of the primitive |
|
6625 |
classes (for example, <code>java.lang.Integer.TYPE</code>). |
|
6626 |
<p/> |
|
6627 |
If the class is a primitive class, its public modifier is always true, |
|
6628 |
and its protected and private modifiers are always false. |
|
6629 |
<p/> |
|
6630 |
If the class is an array class or a primitive class then its final |
|
6631 |
modifier is always true and its interface modifier is always false. |
|
6632 |
The values of its other modifiers are not determined by this specification. |
|
6633 |
||
6634 |
</description> |
|
6635 |
<origin>jvmdi</origin> |
|
6636 |
<capabilities> |
|
6637 |
</capabilities> |
|
6638 |
<parameters> |
|
6639 |
<param id="klass"> |
|
6640 |
<jclass/> |
|
6641 |
<description> |
|
6642 |
The class to query. |
|
6643 |
</description> |
|
6644 |
</param> |
|
6645 |
<param id="modifiers_ptr"> |
|
6646 |
<outptr><jint/></outptr> |
|
6647 |
<description> |
|
6648 |
On return, points to the current access flags of this class. |
|
6649 |
||
6650 |
</description> |
|
6651 |
</param> |
|
6652 |
</parameters> |
|
6653 |
<errors> |
|
6654 |
</errors> |
|
6655 |
</function> |
|
6656 |
||
6657 |
<function id="GetClassMethods" phase="start" num="52"> |
|
6658 |
<synopsis>Get Class Methods</synopsis> |
|
6659 |
<description> |
|
6660 |
For the class indicated by <code>klass</code>, return a count of |
|
6661 |
methods via <code>method_count_ptr</code> and a list of |
|
6662 |
method IDs via <code>methods_ptr</code>. The method list contains |
|
6663 |
constructors and static initializers as well as true methods. |
|
6664 |
Only directly declared methods are returned (not inherited methods). |
|
6665 |
An empty method list is returned for array classes and primitive classes |
|
6666 |
(for example, <code>java.lang.Integer.TYPE</code>). |
|
6667 |
</description> |
|
6668 |
<origin>jvmdi</origin> |
|
6669 |
<capabilities> |
|
6670 |
<capability id="can_maintain_original_method_order"/> |
|
6671 |
</capabilities> |
|
6672 |
<parameters> |
|
6673 |
<param id="klass"> |
|
6674 |
<jclass/> |
|
6675 |
<description> |
|
6676 |
The class to query. |
|
6677 |
</description> |
|
6678 |
</param> |
|
6679 |
<param id="method_count_ptr"> |
|
6680 |
<outptr><jint/></outptr> |
|
6681 |
<description> |
|
6682 |
On return, points to the number of methods declared in this class. |
|
6683 |
</description> |
|
6684 |
</param> |
|
6685 |
<param id="methods_ptr"> |
|
6686 |
<allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf> |
|
6687 |
<description> |
|
6688 |
On return, points to the method ID array. |
|
6689 |
</description> |
|
6690 |
</param> |
|
6691 |
</parameters> |
|
6692 |
<errors> |
|
6693 |
<error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> |
|
6694 |
<paramlink id="klass"></paramlink> is not prepared. |
|
6695 |
</error> |
|
6696 |
</errors> |
|
6697 |
</function> |
|
6698 |
||
6699 |
<function id="GetClassFields" phase="start" num="53"> |
|
6700 |
<synopsis>Get Class Fields</synopsis> |
|
6701 |
<description> |
|
6702 |
For the class indicated by <code>klass</code>, return a count of fields |
|
6703 |
via <code>field_count_ptr</code> and a list of field IDs via |
|
6704 |
<code>fields_ptr</code>. |
|
6705 |
Only directly declared fields are returned (not inherited fields). |
|
6706 |
Fields are returned in the order they occur in the class file. |
|
6707 |
An empty field list is returned for array classes and primitive classes |
|
6708 |
(for example, <code>java.lang.Integer.TYPE</code>). |
|
6709 |
Use JNI to determine the length of an array. |
|
6710 |
</description> |
|
6711 |
<origin>jvmdi</origin> |
|
6712 |
<capabilities> |
|
6713 |
</capabilities> |
|
6714 |
<parameters> |
|
6715 |
<param id="klass"> |
|
6716 |
<jclass/> |
|
6717 |
<description> |
|
6718 |
The class to query. |
|
6719 |
</description> |
|
6720 |
</param> |
|
6721 |
<param id="field_count_ptr"> |
|
6722 |
<outptr><jint/></outptr> |
|
6723 |
<description> |
|
6724 |
On return, points to the number of fields declared in this class. |
|
6725 |
</description> |
|
6726 |
</param> |
|
6727 |
<param id="fields_ptr"> |
|
6728 |
<allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf> |
|
6729 |
<description> |
|
6730 |
On return, points to the field ID array. |
|
6731 |
</description> |
|
6732 |
</param> |
|
6733 |
</parameters> |
|
6734 |
<errors> |
|
6735 |
<error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> |
|
6736 |
<paramlink id="klass"></paramlink> is not prepared. |
|
6737 |
</error> |
|
6738 |
</errors> |
|
6739 |
</function> |
|
6740 |
||
6741 |
<function id="GetImplementedInterfaces" phase="start" num="54"> |
|
6742 |
<synopsis>Get Implemented Interfaces</synopsis> |
|
6743 |
<description> |
|
6744 |
Return the direct super-interfaces of this class. For a class, this |
|
6745 |
function returns the interfaces declared in its <code>implements</code> |
|
6746 |
clause. For an interface, this function returns the interfaces declared in |
|
6747 |
its <code>extends</code> clause. |
|
6748 |
An empty interface list is returned for array classes and primitive classes |
|
6749 |
(for example, <code>java.lang.Integer.TYPE</code>). |
|
6750 |
</description> |
|
6751 |
<origin>jvmdi</origin> |
|
6752 |
<capabilities> |
|
6753 |
</capabilities> |
|
6754 |
<parameters> |
|
6755 |
<param id="klass"> |
|
6756 |
<jclass/> |
|
6757 |
<description> |
|
6758 |
The class to query. |
|
6759 |
</description> |
|
6760 |
</param> |
|
6761 |
<param id="interface_count_ptr"> |
|
6762 |
<outptr><jint/></outptr> |
|
6763 |
<description> |
|
6764 |
On return, points to the number of interfaces. |
|
6765 |
</description> |
|
6766 |
</param> |
|
6767 |
<param id="interfaces_ptr"> |
|
6768 |
<allocbuf outcount="interface_count_ptr"><jclass/></allocbuf> |
|
6769 |
<description> |
|
6770 |
On return, points to the interface array. |
|
6771 |
</description> |
|
6772 |
</param> |
|
6773 |
</parameters> |
|
6774 |
<errors> |
|
6775 |
<error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> |
|
6776 |
<paramlink id="klass"></paramlink> is not prepared. |
|
6777 |
</error> |
|
6778 |
</errors> |
|
6779 |
</function> |
|
6780 |
||
6781 |
<function id="GetClassVersionNumbers" phase="start" num="145" since="1.1"> |
|
6782 |
<synopsis>Get Class Version Numbers</synopsis> |
|
6783 |
<description> |
|
6784 |
For the class indicated by <code>klass</code>, |
|
6785 |
return the minor and major version numbers, |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
6786 |
as defined in |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
6787 |
<vmspec chapter="4"/>. |
1 | 6788 |
</description> |
6789 |
<origin>new</origin> |
|
6790 |
<capabilities> |
|
6791 |
</capabilities> |
|
6792 |
<parameters> |
|
6793 |
<param id="klass"> |
|
6794 |
<jclass/> |
|
6795 |
<description> |
|
6796 |
The class to query. |
|
6797 |
</description> |
|
6798 |
</param> |
|
6799 |
<param id="minor_version_ptr"> |
|
6800 |
<outptr><jint/></outptr> |
|
6801 |
<description> |
|
6802 |
On return, points to the value of the |
|
6803 |
<code>minor_version</code> item of the |
|
6804 |
Class File Format. |
|
6805 |
Note: to be consistent with the Class File Format, |
|
6806 |
the minor version number is the first parameter. |
|
6807 |
</description> |
|
6808 |
</param> |
|
6809 |
<param id="major_version_ptr"> |
|
6810 |
<outptr><jint/></outptr> |
|
6811 |
<description> |
|
6812 |
On return, points to the value of the |
|
6813 |
<code>major_version</code> item of the |
|
6814 |
Class File Format. |
|
6815 |
</description> |
|
6816 |
</param> |
|
6817 |
</parameters> |
|
6818 |
<errors> |
|
6819 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
6820 |
The class is a primitive or array class. |
|
6821 |
</error> |
|
6822 |
</errors> |
|
6823 |
</function> |
|
6824 |
||
6825 |
<function id="GetConstantPool" phase="start" num="146" since="1.1"> |
|
6826 |
<synopsis>Get Constant Pool</synopsis> |
|
6827 |
<description> |
|
6828 |
For the class indicated by <code>klass</code>, |
|
6829 |
return the raw bytes of the constant pool in the format of the |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
6830 |
<code>constant_pool</code> item of |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
6831 |
<vmspec chapter="4"/>. |
1 | 6832 |
The format of the constant pool may differ between versions |
6833 |
of the Class File Format, so, the |
|
6834 |
<functionlink id="GetClassVersionNumbers">minor and major |
|
6835 |
class version numbers</functionlink> should be checked for |
|
6836 |
compatibility. |
|
6837 |
<p/> |
|
6838 |
The returned constant pool might not have the same layout or |
|
6839 |
contents as the constant pool in the defining class file. |
|
6840 |
The constant pool returned by GetConstantPool() may have |
|
6841 |
more or fewer entries than the defining constant pool. |
|
6842 |
Entries may be in a different order. |
|
6843 |
The constant pool returned by GetConstantPool() will match the |
|
6844 |
constant pool used by |
|
6845 |
<functionlink id="GetBytecodes">GetBytecodes()</functionlink>. |
|
6846 |
That is, the bytecodes returned by GetBytecodes() will have |
|
6847 |
constant pool indices which refer to constant pool entries returned |
|
6848 |
by GetConstantPool(). |
|
6849 |
Note that since <functionlink id="RetransformClasses"/> |
|
6850 |
and <functionlink id="RedefineClasses"/> can change |
|
6851 |
the constant pool, the constant pool returned by this function |
|
6852 |
can change accordingly. Thus, the correspondence between |
|
6853 |
GetConstantPool() and GetBytecodes() does not hold if there |
|
6854 |
is an intervening class retransformation or redefinition. |
|
6855 |
The value of a constant pool entry used by a given bytecode will |
|
6856 |
match that of the defining class file (even if the indices don't match). |
|
6857 |
Constant pool entries which are not used directly or indirectly by |
|
6858 |
bytecodes (for example, UTF-8 strings associated with annotations) are |
|
6859 |
not required to exist in the returned constant pool. |
|
6860 |
</description> |
|
6861 |
<origin>new</origin> |
|
6862 |
<capabilities> |
|
6863 |
<required id="can_get_constant_pool"></required> |
|
6864 |
</capabilities> |
|
6865 |
<parameters> |
|
6866 |
<param id="klass"> |
|
6867 |
<jclass/> |
|
6868 |
<description> |
|
6869 |
The class to query. |
|
6870 |
</description> |
|
6871 |
</param> |
|
6872 |
<param id="constant_pool_count_ptr"> |
|
6873 |
<outptr><jint/></outptr> |
|
6874 |
<description> |
|
6875 |
On return, points to the number of entries |
|
6876 |
in the constant pool table plus one. |
|
6877 |
This corresponds to the <code>constant_pool_count</code> |
|
6878 |
item of the Class File Format. |
|
6879 |
</description> |
|
6880 |
</param> |
|
6881 |
<param id="constant_pool_byte_count_ptr"> |
|
6882 |
<outptr><jint/></outptr> |
|
6883 |
<description> |
|
6884 |
On return, points to the number of bytes |
|
6885 |
in the returned raw constant pool. |
|
6886 |
</description> |
|
6887 |
</param> |
|
6888 |
<param id="constant_pool_bytes_ptr"> |
|
6889 |
<allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf> |
|
6890 |
<description> |
|
6891 |
On return, points to the raw constant pool, that is the bytes |
|
6892 |
defined by the <code>constant_pool</code> item of the |
|
6893 |
Class File Format |
|
6894 |
</description> |
|
6895 |
</param> |
|
6896 |
</parameters> |
|
6897 |
<errors> |
|
6898 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
6899 |
The class is a primitive or array class. |
|
6900 |
</error> |
|
6901 |
</errors> |
|
6902 |
</function> |
|
6903 |
||
6904 |
<function id="IsInterface" phase="start" num="55"> |
|
6905 |
<synopsis>Is Interface</synopsis> |
|
6906 |
<description> |
|
6907 |
Determines whether a class object reference represents an interface. |
|
6908 |
The <code>jboolean</code> result is |
|
6909 |
<code>JNI_TRUE</code> if the "class" is actually an interface, |
|
6910 |
<code>JNI_FALSE</code> otherwise. |
|
6911 |
</description> |
|
6912 |
<origin>jvmdi</origin> |
|
6913 |
<capabilities> |
|
6914 |
</capabilities> |
|
6915 |
<parameters> |
|
6916 |
<param id="klass"> |
|
6917 |
<jclass/> |
|
6918 |
<description> |
|
6919 |
The class to query. |
|
6920 |
</description> |
|
6921 |
</param> |
|
6922 |
<param id="is_interface_ptr"> |
|
6923 |
<outptr><jboolean/></outptr> |
|
6924 |
<description> |
|
6925 |
On return, points to the boolean result of this function. |
|
6926 |
||
6927 |
</description> |
|
6928 |
</param> |
|
6929 |
</parameters> |
|
6930 |
<errors> |
|
6931 |
</errors> |
|
6932 |
</function> |
|
6933 |
||
6934 |
<function id="IsArrayClass" phase="start" num="56"> |
|
6935 |
<synopsis>Is Array Class</synopsis> |
|
6936 |
<description> |
|
6937 |
Determines whether a class object reference represents an array. |
|
6938 |
The <code>jboolean</code> result is |
|
6939 |
<code>JNI_TRUE</code> if the class is an array, |
|
6940 |
<code>JNI_FALSE</code> otherwise. |
|
6941 |
</description> |
|
6942 |
<origin>jvmdi</origin> |
|
6943 |
<capabilities> |
|
6944 |
</capabilities> |
|
6945 |
<parameters> |
|
6946 |
<param id="klass"> |
|
6947 |
<jclass/> |
|
6948 |
<description> |
|
6949 |
The class to query. |
|
6950 |
</description> |
|
6951 |
</param> |
|
6952 |
<param id="is_array_class_ptr"> |
|
6953 |
<outptr><jboolean/></outptr> |
|
6954 |
<description> |
|
6955 |
On return, points to the boolean result of this function. |
|
6956 |
||
6957 |
</description> |
|
6958 |
</param> |
|
6959 |
</parameters> |
|
6960 |
<errors> |
|
6961 |
</errors> |
|
6962 |
</function> |
|
6963 |
||
6964 |
<function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1"> |
|
6965 |
<synopsis>Is Modifiable Class</synopsis> |
|
6966 |
<description> |
|
6967 |
Determines whether a class is modifiable. |
|
6968 |
If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/> |
|
6969 |
returns <code>JNI_TRUE</code>) the class can be |
|
6970 |
redefined with <functionlink id="RedefineClasses"/> (assuming |
|
6971 |
the agent possesses the |
|
6972 |
<fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/> |
|
6973 |
capability) or |
|
6974 |
retransformed with <functionlink id="RetransformClasses"/> (assuming |
|
6975 |
the agent possesses the |
|
6976 |
<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> |
|
6977 |
capability). |
|
6978 |
If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/> |
|
6979 |
returns <code>JNI_FALSE</code>) the class can be neither |
|
6980 |
redefined nor retransformed. |
|
6981 |
<p/> |
|
6982 |
Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) |
|
6983 |
and array classes are never modifiable. |
|
6984 |
<p/> |
|
6985 |
</description> |
|
6986 |
<origin>new</origin> |
|
6987 |
<capabilities> |
|
6988 |
<capability id="can_redefine_any_class"> |
|
6989 |
If possessed then all classes (except primitive and array classes) |
|
6990 |
are modifiable. |
|
6991 |
</capability> |
|
6992 |
<capability id="can_redefine_classes"> |
|
6993 |
No effect on the result of the function. |
|
6994 |
But must additionally be possessed to modify the class with |
|
6995 |
<functionlink id="RedefineClasses"/>. |
|
6996 |
</capability> |
|
6997 |
<capability id="can_retransform_classes"> |
|
6998 |
No effect on the result of the function. |
|
6999 |
But must additionally be possessed to modify the class with |
|
7000 |
<functionlink id="RetransformClasses"/>. |
|
7001 |
</capability> |
|
7002 |
</capabilities> |
|
7003 |
<parameters> |
|
7004 |
<param id="klass"> |
|
7005 |
<jclass/> |
|
7006 |
<description> |
|
7007 |
The class to query. |
|
7008 |
</description> |
|
7009 |
</param> |
|
7010 |
<param id="is_modifiable_class_ptr"> |
|
7011 |
<outptr><jboolean/></outptr> |
|
7012 |
<description> |
|
7013 |
On return, points to the boolean result of this function. |
|
7014 |
</description> |
|
7015 |
</param> |
|
7016 |
</parameters> |
|
7017 |
<errors> |
|
7018 |
</errors> |
|
7019 |
</function> |
|
7020 |
||
7021 |
<function id="GetClassLoader" phase="start" num="57"> |
|
7022 |
<synopsis>Get Class Loader</synopsis> |
|
7023 |
<description> |
|
7024 |
For the class indicated by <code>klass</code>, return via |
|
7025 |
<code>classloader_ptr</code> a reference to the class loader for the |
|
7026 |
class. |
|
7027 |
</description> |
|
7028 |
<origin>jvmdi</origin> |
|
7029 |
<capabilities> |
|
7030 |
</capabilities> |
|
7031 |
<parameters> |
|
7032 |
<param id="klass"> |
|
7033 |
<jclass/> |
|
7034 |
<description> |
|
7035 |
The class to query. |
|
7036 |
</description> |
|
7037 |
</param> |
|
7038 |
<param id="classloader_ptr"> |
|
7039 |
<outptr><jobject/></outptr> |
|
7040 |
<description> |
|
7041 |
On return, points to the class loader that loaded |
|
7042 |
this class. |
|
7043 |
If the class was not created by a class loader |
|
7044 |
or if the class loader is the bootstrap class loader, |
|
7045 |
points to <code>NULL</code>. |
|
7046 |
</description> |
|
7047 |
</param> |
|
7048 |
</parameters> |
|
7049 |
<errors> |
|
7050 |
</errors> |
|
7051 |
||
7052 |
</function> |
|
7053 |
||
7054 |
<function id="GetSourceDebugExtension" phase="start" num="90"> |
|
7055 |
<synopsis>Get Source Debug Extension</synopsis> |
|
7056 |
<description> |
|
7057 |
For the class indicated by <code>klass</code>, return the debug |
|
7058 |
extension via <code>source_debug_extension_ptr</code>. |
|
7059 |
The returned string |
|
7060 |
contains exactly the debug extension information present in the |
|
7061 |
class file of <code>klass</code>. |
|
7062 |
</description> |
|
7063 |
<origin>jvmdi</origin> |
|
7064 |
<capabilities> |
|
7065 |
<required id="can_get_source_debug_extension"></required> |
|
7066 |
</capabilities> |
|
7067 |
<parameters> |
|
7068 |
<param id="klass"> |
|
7069 |
<jclass/> |
|
7070 |
<description> |
|
7071 |
The class to query. |
|
7072 |
</description> |
|
7073 |
</param> |
|
7074 |
<param id="source_debug_extension_ptr"> |
|
7075 |
<allocbuf><char/></allocbuf> |
|
7076 |
<description> |
|
7077 |
On return, points to the class's debug extension, encoded as a |
|
7078 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7079 |
</description> |
|
7080 |
</param> |
|
7081 |
</parameters> |
|
7082 |
<errors> |
|
7083 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
7084 |
Class information does not include a debug extension. |
|
7085 |
</error> |
|
7086 |
</errors> |
|
7087 |
</function> |
|
7088 |
||
7089 |
<function id="RetransformClasses" jkernel="yes" num="152" since="1.1"> |
|
7090 |
<synopsis>Retransform Classes</synopsis> |
|
7091 |
<description> |
|
7092 |
This function facilitates the |
|
7093 |
<internallink id="bci">bytecode instrumentation</internallink> |
|
7094 |
of already loaded classes. |
|
7095 |
To replace the class definition without reference to the existing |
|
7096 |
bytecodes, as one might do when recompiling from source for |
|
7097 |
fix-and-continue debugging, <functionlink id="RedefineClasses"/> |
|
7098 |
function should be used instead. |
|
7099 |
<p/> |
|
7100 |
When classes are initially loaded or when they are |
|
7101 |
<functionlink id="RedefineClasses">redefined</functionlink>, |
|
7102 |
the initial class file bytes can be transformed with the |
|
7103 |
<eventlink id="ClassFileLoadHook"/> event. |
|
7104 |
This function reruns the transformation process |
|
7105 |
(whether or not a transformation has previously occurred). |
|
7106 |
This retransformation follows these steps: |
|
7107 |
<ul> |
|
7108 |
<li>starting from the initial class file bytes |
|
7109 |
</li> |
|
7110 |
<li>for each <fieldlink id="can_retransform_classes" |
|
7111 |
struct="jvmtiCapabilities">retransformation |
|
7112 |
incapable</fieldlink> |
|
7113 |
agent which received a |
|
7114 |
<code>ClassFileLoadHook</code> event during the previous |
|
7115 |
load or redefine, the bytes it returned |
|
7116 |
(via the <code>new_class_data</code> parameter) |
|
7117 |
are reused as the output of the transformation; |
|
7118 |
note that this is equivalent to reapplying |
|
7119 |
the previous transformation, unaltered. except that |
|
7120 |
the <code>ClassFileLoadHook</code> event |
|
7121 |
is <b>not</b> sent to these agents |
|
7122 |
</li> |
|
7123 |
<li>for each <fieldlink id="can_retransform_classes" |
|
7124 |
struct="jvmtiCapabilities">retransformation |
|
7125 |
capable</fieldlink> |
|
7126 |
agent, the <code>ClassFileLoadHook</code> event is sent, |
|
7127 |
allowing a new transformation to be applied |
|
7128 |
</li> |
|
7129 |
<li>the transformed class file bytes are installed as the new |
|
7130 |
definition of the class |
|
7131 |
</li> |
|
7132 |
</ul> |
|
7133 |
See the <eventlink id="ClassFileLoadHook"/> event for more details. |
|
7134 |
<p/> |
|
7135 |
The initial class file bytes represent the bytes passed to |
|
7136 |
<code>ClassLoader.defineClass</code> |
|
7137 |
or <code>RedefineClasses</code> (before any transformations |
|
7138 |
were applied), however they may not exactly match them. |
|
7139 |
The constant pool may differ in ways described in |
|
7140 |
<functionlink id="GetConstantPool"/>. |
|
7141 |
Constant pool indices in the bytecodes of methods will correspond. |
|
7142 |
Some attributes may not be present. |
|
7143 |
Where order is not meaningful, for example the order of methods, |
|
7144 |
order may not be preserved. |
|
7145 |
<p/> |
|
7146 |
Retransformation can cause new versions of methods to be installed. |
|
7147 |
Old method versions may become |
|
7148 |
<internallink id="obsoleteMethods">obsolete</internallink> |
|
7149 |
The new method version will be used on new invokes. |
|
7150 |
If a method has active stack frames, those active frames continue to |
|
7151 |
run the bytecodes of the original method version. |
|
7152 |
<p/> |
|
7153 |
This function does not cause any initialization except that which |
|
7154 |
would occur under the customary JVM semantics. |
|
7155 |
In other words, retransforming a class does not cause its initializers to be |
|
7156 |
run. The values of static fields will remain as they were |
|
7157 |
prior to the call. |
|
7158 |
<p/> |
|
7159 |
Threads need not be suspended. |
|
7160 |
<p/> |
|
7161 |
All breakpoints in the class are cleared. |
|
7162 |
<p/> |
|
7163 |
All attributes are updated. |
|
7164 |
<p/> |
|
7165 |
Instances of the retransformed class are not affected -- fields retain their |
|
7166 |
previous values. |
|
7167 |
<functionlink id="GetTag">Tags</functionlink> on the instances are |
|
7168 |
also unaffected. |
|
7169 |
<p/> |
|
7170 |
In response to this call, no events other than the |
|
7171 |
<eventlink id="ClassFileLoadHook"/> event |
|
7172 |
will be sent. |
|
7173 |
<p/> |
|
7174 |
The retransformation may change method bodies, the constant pool and attributes. |
|
7175 |
The retransformation must not add, remove or rename fields or methods, change the |
|
7176 |
signatures of methods, change modifiers, or change inheritance. |
|
7177 |
These restrictions may be lifted in future versions. |
|
7178 |
See the error return description below for information on error codes |
|
7179 |
returned if an unsupported retransformation is attempted. |
|
7180 |
The class file bytes are not verified or installed until they have passed |
|
7181 |
through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the |
|
7182 |
returned error code reflects the result of the transformations. |
|
7183 |
If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, |
|
7184 |
none of the classes to be retransformed will have a new definition installed. |
|
7185 |
When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) |
|
7186 |
all of the classes to be retransformed will have their new definitions installed. |
|
7187 |
</description> |
|
7188 |
<origin>new</origin> |
|
7189 |
<capabilities> |
|
7190 |
<required id="can_retransform_classes"></required> |
|
7191 |
<capability id="can_retransform_any_class"></capability> |
|
7192 |
</capabilities> |
|
7193 |
<parameters> |
|
7194 |
<param id="class_count"> |
|
7195 |
<jint min="0"/> |
|
7196 |
<description> |
|
7197 |
The number of classes to be retransformed. |
|
7198 |
</description> |
|
7199 |
</param> |
|
7200 |
<param id="classes"> |
|
7201 |
<inbuf incount="class_count"><jclass/></inbuf> |
|
7202 |
<description> |
|
7203 |
The array of classes to be retransformed. |
|
7204 |
</description> |
|
7205 |
</param> |
|
7206 |
</parameters> |
|
7207 |
<errors> |
|
7208 |
<error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> |
|
7209 |
One of the <paramlink id="classes"/> cannot be modified. |
|
7210 |
See <functionlink id="IsModifiableClass"/>. |
|
7211 |
</error> |
|
7212 |
<error id="JVMTI_ERROR_INVALID_CLASS"> |
|
7213 |
One of the <paramlink id="classes"/> is not a valid class. |
|
7214 |
</error> |
|
7215 |
<error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> |
|
7216 |
A retransformed class file has a version number not supported by this VM. |
|
7217 |
</error> |
|
7218 |
<error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> |
|
7219 |
A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>). |
|
7220 |
</error> |
|
7221 |
<error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> |
|
7222 |
The retransformed class file definitions would lead to a circular definition |
|
7223 |
(the VM would return a <code>ClassCircularityError</code>). |
|
7224 |
</error> |
|
7225 |
<error id="JVMTI_ERROR_FAILS_VERIFICATION"> |
|
7226 |
The retransformed class file bytes fail verification. |
|
7227 |
</error> |
|
7228 |
<error id="JVMTI_ERROR_NAMES_DONT_MATCH"> |
|
7229 |
The class name defined in a retransformed class file is |
|
7230 |
different from the name in the old class object. |
|
7231 |
</error> |
|
7232 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> |
|
7233 |
A retransformed class file would require adding a method. |
|
7234 |
</error> |
|
7235 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> |
|
7236 |
A retransformed class file changes a field. |
|
7237 |
</error> |
|
7238 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> |
|
7239 |
A direct superclass is different for a retransformed class file, |
|
7240 |
or the set of directly implemented |
|
7241 |
interfaces is different. |
|
7242 |
</error> |
|
7243 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> |
|
7244 |
A retransformed class file does not declare a method |
|
7245 |
declared in the old class version. |
|
7246 |
</error> |
|
7247 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> |
|
7248 |
A retransformed class file has different class modifiers. |
|
7249 |
</error> |
|
7250 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> |
|
7251 |
A method in the retransformed class file has different modifiers |
|
7252 |
than its counterpart in the old class version. |
|
7253 |
</error> |
|
7254 |
</errors> |
|
7255 |
</function> |
|
7256 |
||
7257 |
<function id="RedefineClasses" jkernel="yes" num="87"> |
|
7258 |
<synopsis>Redefine Classes</synopsis> |
|
7259 |
<typedef id="jvmtiClassDefinition" label="Class redefinition description"> |
|
7260 |
<field id="klass"> |
|
7261 |
<jclass/> |
|
7262 |
<description> |
|
7263 |
Class object for this class |
|
7264 |
</description> |
|
7265 |
</field> |
|
7266 |
<field id="class_byte_count"> |
|
7267 |
<jint/> |
|
7268 |
<description> |
|
7269 |
Number of bytes defining class (below) |
|
7270 |
</description> |
|
7271 |
</field> |
|
7272 |
<field id="class_bytes"> |
|
7273 |
<inbuf incount="class_byte_count"><uchar/></inbuf> |
|
7274 |
<description> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7275 |
Bytes defining class (in <vmspec chapter="4"/>) |
1 | 7276 |
</description> |
7277 |
</field> |
|
7278 |
</typedef> |
|
7279 |
<description> |
|
7280 |
All classes given are redefined according to the definitions |
|
7281 |
supplied. |
|
7282 |
This function is used to replace the definition of a class |
|
7283 |
with a new definition, as might be needed in fix-and-continue |
|
7284 |
debugging. |
|
7285 |
Where the existing class file bytes are to be transformed, for |
|
7286 |
example in |
|
7287 |
<internallink id="bci">bytecode instrumentation</internallink>, |
|
7288 |
<functionlink id="RetransformClasses"/> should be used. |
|
7289 |
<p/> |
|
7290 |
Redefinition can cause new versions of methods to be installed. |
|
7291 |
Old method versions may become |
|
7292 |
<internallink id="obsoleteMethods">obsolete</internallink> |
|
7293 |
The new method version will be used on new invokes. |
|
7294 |
If a method has active stack frames, those active frames continue to |
|
7295 |
run the bytecodes of the original method version. |
|
7296 |
If resetting of stack frames is desired, use |
|
7297 |
<functionlink id="PopFrame"></functionlink> |
|
7298 |
to pop frames with obsolete method versions. |
|
7299 |
<p/> |
|
7300 |
This function does not cause any initialization except that which |
|
7301 |
would occur under the customary JVM semantics. |
|
7302 |
In other words, redefining a class does not cause its initializers to be |
|
7303 |
run. The values of static fields will remain as they were |
|
7304 |
prior to the call. |
|
7305 |
<p/> |
|
7306 |
Threads need not be suspended. |
|
7307 |
<p/> |
|
7308 |
All breakpoints in the class are cleared. |
|
7309 |
<p/> |
|
7310 |
All attributes are updated. |
|
7311 |
<p/> |
|
7312 |
Instances of the redefined class are not affected -- fields retain their |
|
7313 |
previous values. |
|
7314 |
<functionlink id="GetTag">Tags</functionlink> on the instances are |
|
7315 |
also unaffected. |
|
7316 |
<p/> |
|
7317 |
In response to this call, the <jvmti/> event |
|
7318 |
<eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink> |
|
7319 |
will be sent (if enabled), but no other <jvmti/> events will be sent. |
|
7320 |
<p/> |
|
7321 |
The redefinition may change method bodies, the constant pool and attributes. |
|
7322 |
The redefinition must not add, remove or rename fields or methods, change the |
|
7323 |
signatures of methods, change modifiers, or change inheritance. |
|
7324 |
These restrictions may be lifted in future versions. |
|
7325 |
See the error return description below for information on error codes |
|
7326 |
returned if an unsupported redefinition is attempted. |
|
7327 |
The class file bytes are not verified or installed until they have passed |
|
7328 |
through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the |
|
7329 |
returned error code reflects the result of the transformations applied |
|
7330 |
to the bytes passed into <paramlink id="class_definitions"/>. |
|
7331 |
If any error code is returned other than <code>JVMTI_ERROR_NONE</code>, |
|
7332 |
none of the classes to be redefined will have a new definition installed. |
|
7333 |
When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>) |
|
7334 |
all of the classes to be redefined will have their new definitions installed. |
|
7335 |
</description> |
|
7336 |
<origin>jvmdi</origin> |
|
7337 |
<capabilities> |
|
7338 |
<required id="can_redefine_classes"></required> |
|
7339 |
<capability id="can_redefine_any_class"></capability> |
|
7340 |
</capabilities> |
|
7341 |
<parameters> |
|
7342 |
<param id="class_count"> |
|
7343 |
<jint min="0"/> |
|
7344 |
<description> |
|
7345 |
The number of classes specified in <code>class_definitions</code> |
|
7346 |
</description> |
|
7347 |
</param> |
|
7348 |
<param id="class_definitions"> |
|
7349 |
<inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf> |
|
7350 |
<description> |
|
7351 |
The array of new class definitions |
|
7352 |
</description> |
|
7353 |
</param> |
|
7354 |
</parameters> |
|
7355 |
<errors> |
|
7356 |
<error id="JVMTI_ERROR_NULL_POINTER"> |
|
7357 |
One of <code>class_bytes</code> is <code>NULL</code>. |
|
7358 |
</error> |
|
7359 |
<error id="JVMTI_ERROR_UNMODIFIABLE_CLASS"> |
|
7360 |
An element of <code>class_definitions</code> cannot be modified. |
|
7361 |
See <functionlink id="IsModifiableClass"/>. |
|
7362 |
</error> |
|
7363 |
<error id="JVMTI_ERROR_INVALID_CLASS"> |
|
7364 |
An element of <code>class_definitions</code> is not a valid class. |
|
7365 |
</error> |
|
7366 |
<error id="JVMTI_ERROR_UNSUPPORTED_VERSION"> |
|
7367 |
A new class file has a version number not supported by this VM. |
|
7368 |
</error> |
|
7369 |
<error id="JVMTI_ERROR_INVALID_CLASS_FORMAT"> |
|
7370 |
A new class file is malformed (The VM would return a <code>ClassFormatError</code>). |
|
7371 |
</error> |
|
7372 |
<error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION"> |
|
7373 |
The new class file definitions would lead to a circular definition |
|
7374 |
(the VM would return a <code>ClassCircularityError</code>). |
|
7375 |
</error> |
|
7376 |
<error id="JVMTI_ERROR_FAILS_VERIFICATION"> |
|
7377 |
The class bytes fail verification. |
|
7378 |
</error> |
|
7379 |
<error id="JVMTI_ERROR_NAMES_DONT_MATCH"> |
|
7380 |
The class name defined in a new class file is |
|
7381 |
different from the name in the old class object. |
|
7382 |
</error> |
|
7383 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED"> |
|
7384 |
A new class file would require adding a method. |
|
7385 |
</error> |
|
7386 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED"> |
|
7387 |
A new class version changes a field. |
|
7388 |
</error> |
|
7389 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED"> |
|
7390 |
A direct superclass is different for a new class |
|
7391 |
version, or the set of directly implemented |
|
7392 |
interfaces is different. |
|
7393 |
</error> |
|
7394 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED"> |
|
7395 |
A new class version does not declare a method |
|
7396 |
declared in the old class version. |
|
7397 |
</error> |
|
7398 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED"> |
|
7399 |
A new class version has different modifiers. |
|
7400 |
</error> |
|
7401 |
<error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED"> |
|
7402 |
A method in the new class version has different modifiers |
|
7403 |
than its counterpart in the old class version. |
|
7404 |
</error> |
|
7405 |
</errors> |
|
7406 |
</function> |
|
7407 |
||
7408 |
</category> |
|
7409 |
||
7410 |
<category id="object" label="Object"> |
|
7411 |
||
7412 |
<function id="GetObjectSize" jkernel="yes" phase="start" num="154"> |
|
7413 |
<synopsis>Get Object Size</synopsis> |
|
7414 |
<description> |
|
7415 |
For the object indicated by <code>object</code>, |
|
7416 |
return via <code>size_ptr</code> the size of the object. |
|
7417 |
This size is an implementation-specific approximation of |
|
7418 |
the amount of storage consumed by this object. |
|
7419 |
It may include some or all of the object's overhead, and thus |
|
7420 |
is useful for comparison within an implementation but not |
|
7421 |
between implementations. |
|
7422 |
The estimate may change during a single invocation of the JVM. |
|
7423 |
</description> |
|
7424 |
<origin>new</origin> |
|
7425 |
<capabilities> |
|
7426 |
</capabilities> |
|
7427 |
<parameters> |
|
7428 |
<param id="object"> |
|
7429 |
<jobject/> |
|
7430 |
<description> |
|
7431 |
The object to query. |
|
7432 |
</description> |
|
7433 |
</param> |
|
7434 |
<param id="size_ptr"> |
|
7435 |
<outptr><jlong/></outptr> |
|
7436 |
<description> |
|
7437 |
On return, points to the object's size in bytes. |
|
7438 |
</description> |
|
7439 |
</param> |
|
7440 |
</parameters> |
|
7441 |
<errors> |
|
7442 |
</errors> |
|
7443 |
</function> |
|
7444 |
||
7445 |
<function id="GetObjectHashCode" phase="start" num="58"> |
|
7446 |
<synopsis>Get Object Hash Code</synopsis> |
|
7447 |
<description> |
|
7448 |
For the object indicated by <code>object</code>, |
|
7449 |
return via <code>hash_code_ptr</code> a hash code. |
|
7450 |
This hash code could be used to maintain a hash table of object references, |
|
7451 |
however, on some implementations this can cause significant performance |
|
7452 |
impacts--in most cases |
|
7453 |
<internallink id="Heap">tags</internallink> |
|
7454 |
will be a more efficient means of associating information with objects. |
|
7455 |
This function guarantees |
|
7456 |
the same hash code value for a particular object throughout its life |
|
7457 |
</description> |
|
7458 |
<origin>jvmdi</origin> |
|
7459 |
<capabilities> |
|
7460 |
</capabilities> |
|
7461 |
<parameters> |
|
7462 |
<param id="object"> |
|
7463 |
<jobject/> |
|
7464 |
<description> |
|
7465 |
The object to query. |
|
7466 |
</description> |
|
7467 |
</param> |
|
7468 |
<param id="hash_code_ptr"> |
|
7469 |
<outptr><jint/></outptr> |
|
7470 |
<description> |
|
7471 |
On return, points to the object's hash code. |
|
7472 |
</description> |
|
7473 |
</param> |
|
7474 |
</parameters> |
|
7475 |
<errors> |
|
7476 |
</errors> |
|
7477 |
</function> |
|
7478 |
||
7479 |
<function id="GetObjectMonitorUsage" num="59"> |
|
7480 |
<synopsis>Get Object Monitor Usage</synopsis> |
|
7481 |
<typedef id="jvmtiMonitorUsage" label="Object monitor usage information"> |
|
7482 |
<field id="owner"> |
|
7483 |
<jthread/> |
|
7484 |
<description> |
|
7485 |
The thread owning this monitor, or <code>NULL</code> if unused |
|
7486 |
</description> |
|
7487 |
</field> |
|
7488 |
<field id="entry_count"> |
|
7489 |
<jint/> |
|
7490 |
<description> |
|
7491 |
The number of times the owning thread has entered the monitor |
|
7492 |
</description> |
|
7493 |
</field> |
|
7494 |
<field id="waiter_count"> |
|
7495 |
<jint/> |
|
7496 |
<description> |
|
7497 |
The number of threads waiting to own this monitor |
|
7498 |
</description> |
|
7499 |
</field> |
|
7500 |
<field id="waiters"> |
|
7501 |
<allocfieldbuf><jthread/></allocfieldbuf> |
|
7502 |
<description> |
|
7503 |
The <code>waiter_count</code> waiting threads |
|
7504 |
</description> |
|
7505 |
</field> |
|
7506 |
<field id="notify_waiter_count"> |
|
7507 |
<jint/> |
|
7508 |
<description> |
|
7509 |
The number of threads waiting to be notified by this monitor |
|
7510 |
</description> |
|
7511 |
</field> |
|
7512 |
<field id="notify_waiters"> |
|
7513 |
<allocfieldbuf><jthread/></allocfieldbuf> |
|
7514 |
<description> |
|
7515 |
The <code>notify_waiter_count</code> threads waiting to be notified |
|
7516 |
</description> |
|
7517 |
</field> |
|
7518 |
</typedef> |
|
7519 |
<description> |
|
7520 |
Get information about the object's monitor. |
|
7521 |
The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure |
|
7522 |
are filled in with information about usage of the monitor. |
|
7523 |
<todo> |
|
7524 |
Decide and then clarify suspend requirements. |
|
7525 |
</todo> |
|
7526 |
</description> |
|
7527 |
<origin>jvmdi</origin> |
|
7528 |
<capabilities> |
|
7529 |
<required id="can_get_monitor_info"></required> |
|
7530 |
</capabilities> |
|
7531 |
<parameters> |
|
7532 |
<param id="object"> |
|
7533 |
<jobject/> |
|
7534 |
<description> |
|
7535 |
The object to query. |
|
7536 |
</description> |
|
7537 |
</param> |
|
7538 |
<param id="info_ptr"> |
|
7539 |
<outptr><struct>jvmtiMonitorUsage</struct></outptr> |
|
7540 |
<description> |
|
7541 |
On return, filled with monitor information for the |
|
7542 |
specified object. |
|
7543 |
</description> |
|
7544 |
</param> |
|
7545 |
</parameters> |
|
7546 |
<errors> |
|
7547 |
</errors> |
|
7548 |
</function> |
|
7549 |
||
7550 |
<elide> |
|
7551 |
<function id="GetObjectMonitors" num="116"> |
|
7552 |
<synopsis>Get Object Monitors</synopsis> |
|
7553 |
<description> |
|
7554 |
Return the list of object monitors. |
|
7555 |
<p/> |
|
7556 |
Note: details about each monitor can be examined with |
|
7557 |
<functionlink id="GetObjectMonitorUsage"></functionlink>. |
|
7558 |
</description> |
|
7559 |
<origin>new</origin> |
|
7560 |
<capabilities> |
|
7561 |
<required id="can_get_monitor_info"></required> |
|
7562 |
</capabilities> |
|
7563 |
<parameters> |
|
7564 |
<param id="monitorCnt"> |
|
7565 |
<outptr><jint/></outptr> |
|
7566 |
<description> |
|
7567 |
On return, pointer to the number |
|
7568 |
of monitors returned in <code>monitors_ptr</code>. |
|
7569 |
</description> |
|
7570 |
</param> |
|
7571 |
<param id="monitors_ptr"> |
|
7572 |
<allocbuf outcount="monitorCnt"><jobject/></allocbuf> |
|
7573 |
<description> |
|
7574 |
On return, pointer to the monitor list. |
|
7575 |
</description> |
|
7576 |
</param> |
|
7577 |
</parameters> |
|
7578 |
<errors> |
|
7579 |
</errors> |
|
7580 |
</function> |
|
7581 |
</elide> |
|
7582 |
||
7583 |
</category> |
|
7584 |
||
7585 |
<category id="fieldCategory" label="Field"> |
|
7586 |
||
7587 |
<intro> |
|
7588 |
</intro> |
|
7589 |
||
7590 |
<function id="GetFieldName" phase="start" num="60"> |
|
7591 |
<synopsis>Get Field Name (and Signature)</synopsis> |
|
7592 |
<description> |
|
7593 |
For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>, |
|
7594 |
return the field name via <paramlink id="name_ptr"/> and field signature via |
|
7595 |
<paramlink id="signature_ptr"/>. |
|
7596 |
<p/> |
|
7597 |
Field signatures are defined in the JNI Specification and |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7598 |
are referred to as <code>field descriptors</code> in |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7599 |
<vmspec chapter="4.3.2"/>. |
1 | 7600 |
</description> |
7601 |
<origin>jvmdiClone</origin> |
|
7602 |
<capabilities> |
|
7603 |
</capabilities> |
|
7604 |
<parameters> |
|
7605 |
<param id="klass"> |
|
7606 |
<jclass field="field"/> |
|
7607 |
<description> |
|
7608 |
The class of the field to query. |
|
7609 |
</description> |
|
7610 |
</param> |
|
7611 |
<param id="field"> |
|
7612 |
<jfieldID class="klass"/> |
|
7613 |
<description> |
|
7614 |
The field to query. |
|
7615 |
</description> |
|
7616 |
</param> |
|
7617 |
<param id="name_ptr"> |
|
7618 |
<allocbuf> |
|
7619 |
<char/> |
|
7620 |
<nullok>the name is not returned</nullok> |
|
7621 |
</allocbuf> |
|
7622 |
<description> |
|
7623 |
On return, points to the field name, encoded as a |
|
7624 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7625 |
</description> |
|
7626 |
</param> |
|
7627 |
<param id="signature_ptr"> |
|
7628 |
<allocbuf> |
|
7629 |
<char/> |
|
7630 |
<nullok>the signature is not returned</nullok> |
|
7631 |
</allocbuf> |
|
7632 |
<description> |
|
7633 |
On return, points to the field signature, encoded as a |
|
7634 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7635 |
</description> |
|
7636 |
</param> |
|
7637 |
<param id="generic_ptr"> |
|
7638 |
<allocbuf> |
|
7639 |
<char/> |
|
7640 |
<nullok>the generic signature is not returned</nullok> |
|
7641 |
</allocbuf> |
|
7642 |
<description> |
|
7643 |
On return, points to the generic signature of the field, encoded as a |
|
7644 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7645 |
If there is no generic signature attribute for the field, then, |
|
7646 |
on return, points to <code>NULL</code>. |
|
7647 |
</description> |
|
7648 |
</param> |
|
7649 |
</parameters> |
|
7650 |
<errors> |
|
7651 |
</errors> |
|
7652 |
</function> |
|
7653 |
||
7654 |
<function id="GetFieldDeclaringClass" phase="start" num="61"> |
|
7655 |
<synopsis>Get Field Declaring Class</synopsis> |
|
7656 |
<description> |
|
7657 |
For the field indicated by <code>klass</code> and <code>field</code> |
|
7658 |
return the class that defined it via <code>declaring_class_ptr</code>. |
|
7659 |
The declaring class will either be <code>klass</code>, a superclass, or |
|
7660 |
an implemented interface. |
|
7661 |
</description> |
|
7662 |
<origin>jvmdi</origin> |
|
7663 |
<capabilities> |
|
7664 |
</capabilities> |
|
7665 |
<parameters> |
|
7666 |
<param id="klass"> |
|
7667 |
<jclass field="field"/> |
|
7668 |
<description> |
|
7669 |
The class to query. |
|
7670 |
</description> |
|
7671 |
</param> |
|
7672 |
<param id="field"> |
|
7673 |
<jfieldID class="klass"/> |
|
7674 |
<description> |
|
7675 |
The field to query. |
|
7676 |
</description> |
|
7677 |
</param> |
|
7678 |
<param id="declaring_class_ptr"> |
|
7679 |
<outptr><jclass/></outptr> |
|
7680 |
<description> |
|
7681 |
On return, points to the declaring class |
|
7682 |
</description> |
|
7683 |
</param> |
|
7684 |
</parameters> |
|
7685 |
<errors> |
|
7686 |
</errors> |
|
7687 |
</function> |
|
7688 |
||
7689 |
<function id="GetFieldModifiers" phase="start" num="62"> |
|
7690 |
<synopsis>Get Field Modifiers</synopsis> |
|
7691 |
<description> |
|
7692 |
For the field indicated by <code>klass</code> and <code>field</code> |
|
7693 |
return the access flags via <code>modifiers_ptr</code>. |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7694 |
Access flags are defined in <vmspec chapter="4"/>. |
1 | 7695 |
</description> |
7696 |
<origin>jvmdi</origin> |
|
7697 |
<capabilities> |
|
7698 |
</capabilities> |
|
7699 |
<parameters> |
|
7700 |
<param id="klass"> |
|
7701 |
<jclass field="field"/> |
|
7702 |
<description> |
|
7703 |
The class to query. |
|
7704 |
</description> |
|
7705 |
</param> |
|
7706 |
<param id="field"> |
|
7707 |
<jfieldID class="klass"/> |
|
7708 |
<description> |
|
7709 |
The field to query. |
|
7710 |
</description> |
|
7711 |
</param> |
|
7712 |
<param id="modifiers_ptr"> |
|
7713 |
<outptr><jint/></outptr> |
|
7714 |
<description> |
|
7715 |
On return, points to the access flags. |
|
7716 |
</description> |
|
7717 |
</param> |
|
7718 |
</parameters> |
|
7719 |
<errors> |
|
7720 |
</errors> |
|
7721 |
</function> |
|
7722 |
||
7723 |
<function id="IsFieldSynthetic" phase="start" num="63"> |
|
7724 |
<synopsis>Is Field Synthetic</synopsis> |
|
7725 |
<description> |
|
7726 |
For the field indicated by <code>klass</code> and <code>field</code>, return a |
|
7727 |
value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>. |
|
7728 |
Synthetic fields are generated by the compiler but not present in the |
|
7729 |
original source code. |
|
7730 |
</description> |
|
7731 |
<origin>jvmdi</origin> |
|
7732 |
<capabilities> |
|
7733 |
<required id="can_get_synthetic_attribute"></required> |
|
7734 |
</capabilities> |
|
7735 |
<parameters> |
|
7736 |
<param id="klass"> |
|
7737 |
<jclass field="field"/> |
|
7738 |
<description> |
|
7739 |
The class of the field to query. |
|
7740 |
</description> |
|
7741 |
</param> |
|
7742 |
<param id="field"> |
|
7743 |
<jfieldID class="klass"/> |
|
7744 |
<description> |
|
7745 |
The field to query. |
|
7746 |
</description> |
|
7747 |
</param> |
|
7748 |
<param id="is_synthetic_ptr"> |
|
7749 |
<outptr><jboolean/></outptr> |
|
7750 |
<description> |
|
7751 |
On return, points to the boolean result of this function. |
|
7752 |
</description> |
|
7753 |
</param> |
|
7754 |
</parameters> |
|
7755 |
<errors> |
|
7756 |
</errors> |
|
7757 |
</function> |
|
7758 |
||
7759 |
</category> |
|
7760 |
||
7761 |
<category id="method" label="Method"> |
|
7762 |
||
7763 |
<intro> |
|
7764 |
These functions provide information about a method (represented as a |
|
7765 |
<typelink id="jmethodID"/>) and set how methods are processed. |
|
7766 |
</intro> |
|
7767 |
||
7768 |
<intro id="obsoleteMethods" label="Obsolete Methods"> |
|
7769 |
The functions <functionlink id="RetransformClasses"/> and |
|
7770 |
<functionlink id="RedefineClasses"/> can cause new versions |
|
7771 |
of methods to be installed. |
|
7772 |
An original version of a method is considered equivalent |
|
7773 |
to the new version if: |
|
7774 |
<ul> |
|
7775 |
<li>their bytecodes are the same except for indices into the |
|
7776 |
constant pool and </li> |
|
7777 |
<li>the referenced constants are equal.</li> |
|
7778 |
</ul> |
|
7779 |
An original method version which is not equivalent to the |
|
7780 |
new method version is called obsolete and is assigned a new method ID; |
|
7781 |
the original method ID now refers to the new method version. |
|
7782 |
A method ID can be tested for obsolescence with |
|
7783 |
<functionlink id="IsMethodObsolete"/>. |
|
7784 |
</intro> |
|
7785 |
||
7786 |
<function id="GetMethodName" phase="start" num="64"> |
|
7787 |
<synopsis>Get Method Name (and Signature)</synopsis> |
|
7788 |
<description> |
|
7789 |
For the method indicated by <code>method</code>, |
|
7790 |
return the method name via <code>name_ptr</code> and method signature via |
|
7791 |
<code>signature_ptr</code>. |
|
7792 |
<p/> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7793 |
Method signatures are defined in the JNI Specification and are |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7794 |
referred to as <code>method descriptors</code> in |
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7795 |
<vmspec chapter="4.3.3"/>. |
1 | 7796 |
Note this is different |
7797 |
than method signatures as defined in the <i>Java Language Specification</i>. |
|
7798 |
</description> |
|
7799 |
<origin>jvmdiClone</origin> |
|
7800 |
<capabilities> |
|
7801 |
</capabilities> |
|
7802 |
<parameters> |
|
7803 |
<param id="method"> |
|
7804 |
<jmethodID/> |
|
7805 |
<description> |
|
7806 |
The method to query. |
|
7807 |
</description> |
|
7808 |
</param> |
|
7809 |
<param id="name_ptr"> |
|
7810 |
<allocbuf> |
|
7811 |
<char/> |
|
7812 |
<nullok>the name is not returned</nullok> |
|
7813 |
</allocbuf> |
|
7814 |
<description> |
|
7815 |
On return, points to the method name, encoded as a |
|
7816 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7817 |
</description> |
|
7818 |
</param> |
|
7819 |
<param id="signature_ptr"> |
|
7820 |
<allocbuf> |
|
7821 |
<char/> |
|
7822 |
<nullok>the signature is not returned</nullok> |
|
7823 |
</allocbuf> |
|
7824 |
<description> |
|
7825 |
On return, points to the method signature, encoded as a |
|
7826 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7827 |
</description> |
|
7828 |
</param> |
|
7829 |
<param id="generic_ptr"> |
|
7830 |
<allocbuf> |
|
7831 |
<char/> |
|
7832 |
<nullok>the generic signature is not returned</nullok> |
|
7833 |
</allocbuf> |
|
7834 |
<description> |
|
7835 |
On return, points to the generic signature of the method, encoded as a |
|
7836 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
7837 |
If there is no generic signature attribute for the method, then, |
|
7838 |
on return, points to <code>NULL</code>. |
|
7839 |
</description> |
|
7840 |
</param> |
|
7841 |
</parameters> |
|
7842 |
<errors> |
|
7843 |
</errors> |
|
7844 |
</function> |
|
7845 |
||
7846 |
<function id="GetMethodDeclaringClass" phase="start" num="65"> |
|
7847 |
<synopsis>Get Method Declaring Class</synopsis> |
|
7848 |
<description> |
|
7849 |
For the method indicated by <code>method</code>, |
|
7850 |
return the class that defined it via <code>declaring_class_ptr</code>. |
|
7851 |
</description> |
|
7852 |
<origin>jvmdi</origin> |
|
7853 |
<capabilities> |
|
7854 |
</capabilities> |
|
7855 |
<parameters> |
|
7856 |
<param id="klass"> |
|
7857 |
<jclass method="method"/> |
|
7858 |
<description> |
|
7859 |
The class to query. |
|
7860 |
</description> |
|
7861 |
</param> |
|
7862 |
<param id="method"> |
|
7863 |
<jmethodID class="klass"/> |
|
7864 |
<description> |
|
7865 |
The method to query. |
|
7866 |
</description> |
|
7867 |
</param> |
|
7868 |
<param id="declaring_class_ptr"> |
|
7869 |
<outptr><jclass/></outptr> |
|
7870 |
<description> |
|
7871 |
On return, points to the declaring class |
|
7872 |
</description> |
|
7873 |
</param> |
|
7874 |
</parameters> |
|
7875 |
<errors> |
|
7876 |
</errors> |
|
7877 |
</function> |
|
7878 |
||
7879 |
<function id="GetMethodModifiers" phase="start" num="66"> |
|
7880 |
<synopsis>Get Method Modifiers</synopsis> |
|
7881 |
<description> |
|
7882 |
For the method indicated by <code>method</code>, |
|
7883 |
return the access flags via <code>modifiers_ptr</code>. |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7884 |
Access flags are defined in <vmspec chapter="4"/>. |
1 | 7885 |
</description> |
7886 |
<origin>jvmdi</origin> |
|
7887 |
<capabilities> |
|
7888 |
</capabilities> |
|
7889 |
<parameters> |
|
7890 |
<param id="klass"> |
|
7891 |
<jclass method="method"/> |
|
7892 |
<description> |
|
7893 |
The class to query. |
|
7894 |
</description> |
|
7895 |
</param> |
|
7896 |
<param id="method"> |
|
7897 |
<jmethodID class="klass"/> |
|
7898 |
<description> |
|
7899 |
The method to query. |
|
7900 |
</description> |
|
7901 |
</param> |
|
7902 |
<param id="modifiers_ptr"> |
|
7903 |
<outptr><jint/></outptr> |
|
7904 |
<description> |
|
7905 |
On return, points to the access flags. |
|
7906 |
</description> |
|
7907 |
</param> |
|
7908 |
</parameters> |
|
7909 |
<errors> |
|
7910 |
</errors> |
|
7911 |
</function> |
|
7912 |
||
7913 |
<function id="GetMaxLocals" phase="start" num="68"> |
|
7914 |
<synopsis>Get Max Locals</synopsis> |
|
7915 |
<description> |
|
7916 |
For the method indicated by <code>method</code>, |
|
7917 |
return the number of local variable slots used by the method, |
|
7918 |
including the local variables used to pass parameters to the |
|
7919 |
method on its invocation. |
|
7920 |
<p/> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
7921 |
See <code>max_locals</code> in <vmspec chapter="4.7.3"/>. |
1 | 7922 |
</description> |
7923 |
<origin>jvmdi</origin> |
|
7924 |
<capabilities> |
|
7925 |
</capabilities> |
|
7926 |
<parameters> |
|
7927 |
<param id="klass"> |
|
7928 |
<jclass method="method"/> |
|
7929 |
<description> |
|
7930 |
The class to query. |
|
7931 |
</description> |
|
7932 |
</param> |
|
7933 |
<param id="method"> |
|
7934 |
<jmethodID class="klass" native="error"/> |
|
7935 |
<description> |
|
7936 |
The method to query. |
|
7937 |
</description> |
|
7938 |
</param> |
|
7939 |
<param id="max_ptr"> |
|
7940 |
<outptr><jint/></outptr> |
|
7941 |
<description> |
|
7942 |
On return, points to the maximum number of local slots |
|
7943 |
</description> |
|
7944 |
</param> |
|
7945 |
</parameters> |
|
7946 |
<errors> |
|
7947 |
</errors> |
|
7948 |
</function> |
|
7949 |
||
7950 |
<function id="GetArgumentsSize" phase="start" num="69"> |
|
7951 |
<synopsis>Get Arguments Size</synopsis> |
|
7952 |
<description> |
|
7953 |
For the method indicated by <code>method</code>, |
|
7954 |
return via <code>max_ptr</code> the number of local variable slots used |
|
7955 |
by the method's arguments. |
|
7956 |
Note that two-word arguments use two slots. |
|
7957 |
</description> |
|
7958 |
<origin>jvmdi</origin> |
|
7959 |
<capabilities> |
|
7960 |
</capabilities> |
|
7961 |
<parameters> |
|
7962 |
<param id="klass"> |
|
7963 |
<jclass method="method"/> |
|
7964 |
<description> |
|
7965 |
The class to query. |
|
7966 |
</description> |
|
7967 |
</param> |
|
7968 |
<param id="method"> |
|
7969 |
<jmethodID class="klass" native="error"/> |
|
7970 |
<description> |
|
7971 |
The method to query. |
|
7972 |
</description> |
|
7973 |
</param> |
|
7974 |
<param id="size_ptr"> |
|
7975 |
<outptr><jint/></outptr> |
|
7976 |
<description> |
|
7977 |
On return, points to the number of argument slots |
|
7978 |
</description> |
|
7979 |
</param> |
|
7980 |
</parameters> |
|
7981 |
<errors> |
|
7982 |
</errors> |
|
7983 |
</function> |
|
7984 |
||
7985 |
<function id="GetLineNumberTable" phase="start" num="70"> |
|
7986 |
<synopsis>Get Line Number Table</synopsis> |
|
7987 |
<typedef id="jvmtiLineNumberEntry" label="Line number table entry"> |
|
7988 |
<field id="start_location"> |
|
7989 |
<jlocation/> |
|
7990 |
<description> |
|
7991 |
the <datalink id="jlocation"></datalink> where the line begins |
|
7992 |
</description> |
|
7993 |
</field> |
|
7994 |
<field id="line_number"> |
|
7995 |
<jint/> |
|
7996 |
<description> |
|
7997 |
the line number |
|
7998 |
</description> |
|
7999 |
</field> |
|
8000 |
</typedef> |
|
8001 |
<description> |
|
8002 |
For the method indicated by <code>method</code>, |
|
8003 |
return a table of source line number entries. The size of the table is |
|
8004 |
returned via <code>entry_count_ptr</code> and the table itself is |
|
8005 |
returned via <code>table_ptr</code>. |
|
8006 |
</description> |
|
8007 |
<origin>jvmdi</origin> |
|
8008 |
<capabilities> |
|
8009 |
<required id="can_get_line_numbers"></required> |
|
8010 |
</capabilities> |
|
8011 |
<parameters> |
|
8012 |
<param id="klass"> |
|
8013 |
<jclass method="method"/> |
|
8014 |
<description> |
|
8015 |
The class to query. |
|
8016 |
</description> |
|
8017 |
</param> |
|
8018 |
<param id="method"> |
|
8019 |
<jmethodID class="klass" native="error"/> |
|
8020 |
<description> |
|
8021 |
The method to query. |
|
8022 |
</description> |
|
8023 |
</param> |
|
8024 |
<param id="entry_count_ptr"> |
|
8025 |
<outptr><jint/></outptr> |
|
8026 |
<description> |
|
8027 |
On return, points to the number of entries in the table |
|
8028 |
</description> |
|
8029 |
</param> |
|
8030 |
<param id="table_ptr"> |
|
8031 |
<allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf> |
|
8032 |
<description> |
|
8033 |
On return, points to the line number table pointer. |
|
8034 |
</description> |
|
8035 |
</param> |
|
8036 |
</parameters> |
|
8037 |
<errors> |
|
8038 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
8039 |
Class information does not include line numbers. |
|
8040 |
</error> |
|
8041 |
</errors> |
|
8042 |
</function> |
|
8043 |
||
8044 |
<function id="GetMethodLocation" phase="start" num="71"> |
|
8045 |
<synopsis>Get Method Location</synopsis> |
|
8046 |
<description> |
|
8047 |
For the method indicated by <code>method</code>, |
|
8048 |
return the beginning and ending addresses through |
|
8049 |
<code>start_location_ptr</code> and <code>end_location_ptr</code>. In a |
|
8050 |
conventional byte code indexing scheme, |
|
8051 |
<code>start_location_ptr</code> will always point to zero |
|
8052 |
and <code>end_location_ptr</code> |
|
8053 |
will always point to the byte code count minus one. |
|
8054 |
</description> |
|
8055 |
<origin>jvmdi</origin> |
|
8056 |
<capabilities> |
|
8057 |
</capabilities> |
|
8058 |
<parameters> |
|
8059 |
<param id="klass"> |
|
8060 |
<jclass method="method"/> |
|
8061 |
<description> |
|
8062 |
The class to query. |
|
8063 |
</description> |
|
8064 |
</param> |
|
8065 |
<param id="method"> |
|
8066 |
<jmethodID class="klass" native="error"/> |
|
8067 |
<description> |
|
8068 |
The method to query. |
|
8069 |
</description> |
|
8070 |
</param> |
|
8071 |
<param id="start_location_ptr"> |
|
8072 |
<outptr><jlocation/></outptr> |
|
8073 |
<description> |
|
8074 |
On return, points to the first location, or |
|
8075 |
<code>-1</code> if location information is not available. |
|
8076 |
If the information is available and |
|
8077 |
<functionlink id="GetJLocationFormat"></functionlink> |
|
8078 |
returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink> |
|
8079 |
then this will always be zero. |
|
8080 |
</description> |
|
8081 |
</param> |
|
8082 |
<param id="end_location_ptr"> |
|
8083 |
<outptr><jlocation/></outptr> |
|
8084 |
<description> |
|
8085 |
On return, points to the last location, |
|
8086 |
or <code>-1</code> if location information is not available. |
|
8087 |
</description> |
|
8088 |
</param> |
|
8089 |
</parameters> |
|
8090 |
<errors> |
|
8091 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
8092 |
Class information does not include method sizes. |
|
8093 |
</error> |
|
8094 |
</errors> |
|
8095 |
</function> |
|
8096 |
||
8097 |
<function id="GetLocalVariableTable" num="72"> |
|
8098 |
<synopsis>Get Local Variable Table</synopsis> |
|
8099 |
<typedef id="jvmtiLocalVariableEntry" label="Local variable table entry"> |
|
8100 |
<field id="start_location"> |
|
8101 |
<jlocation/> |
|
8102 |
<description> |
|
8103 |
The code array index where the local variable is first valid |
|
8104 |
(that is, where it must have a value). |
|
8105 |
</description> |
|
8106 |
</field> |
|
8107 |
<field id="length"> |
|
8108 |
<jint/> |
|
8109 |
<description> |
|
8110 |
The length of the valid section for this local variable. |
|
8111 |
The last code array index where the local variable is valid |
|
8112 |
is <code>start_location + length</code>. |
|
8113 |
</description> |
|
8114 |
</field> |
|
8115 |
<field id="name"> |
|
8116 |
<allocfieldbuf><char/></allocfieldbuf> |
|
8117 |
<description> |
|
8118 |
The local variable name, encoded as a |
|
8119 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
8120 |
</description> |
|
8121 |
</field> |
|
8122 |
<field id="signature"> |
|
8123 |
<allocfieldbuf><char/></allocfieldbuf> |
|
8124 |
<description> |
|
8125 |
The local variable's type signature, encoded as a |
|
8126 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
8127 |
The signature format is the same as that defined in |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
8128 |
<vmspec chapter="4.3.2"/>. |
1 | 8129 |
</description> |
8130 |
</field> |
|
8131 |
<field id="generic_signature"> |
|
8132 |
<allocfieldbuf><char/></allocfieldbuf> |
|
8133 |
<description> |
|
8134 |
The local variable's generic signature, encoded as a |
|
8135 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
8136 |
The value of this field will be <code>NULL</code> for any local |
|
8137 |
variable which does not have a generic type. |
|
8138 |
</description> |
|
8139 |
</field> |
|
8140 |
<field id="slot"> |
|
8141 |
<jint/> |
|
8142 |
<description> |
|
8143 |
The local variable's slot. See <internallink id="local">Local Variables</internallink>. |
|
8144 |
</description> |
|
8145 |
</field> |
|
8146 |
</typedef> |
|
8147 |
<description> |
|
8148 |
Return local variable information. |
|
8149 |
</description> |
|
8150 |
<origin>jvmdiClone</origin> |
|
8151 |
<capabilities> |
|
8152 |
<required id="can_access_local_variables"></required> |
|
8153 |
</capabilities> |
|
8154 |
<parameters> |
|
8155 |
<param id="method"> |
|
8156 |
<jmethodID native="error"/> |
|
8157 |
<description> |
|
8158 |
The method to query. |
|
8159 |
</description> |
|
8160 |
</param> |
|
8161 |
<param id="entry_count_ptr"> |
|
8162 |
<outptr><jint/></outptr> |
|
8163 |
<description> |
|
8164 |
On return, points to the number of entries in the table |
|
8165 |
</description> |
|
8166 |
</param> |
|
8167 |
<param id="table_ptr"> |
|
8168 |
<allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf> |
|
8169 |
<description> |
|
8170 |
On return, points to an array of local variable table entries. |
|
8171 |
</description> |
|
8172 |
</param> |
|
8173 |
</parameters> |
|
8174 |
<errors> |
|
8175 |
<error id="JVMTI_ERROR_ABSENT_INFORMATION"> |
|
8176 |
Class information does not include local variable |
|
8177 |
information. |
|
8178 |
</error> |
|
8179 |
</errors> |
|
8180 |
</function> |
|
8181 |
||
8182 |
<function id="GetBytecodes" phase="start" num="75"> |
|
8183 |
<synopsis>Get Bytecodes</synopsis> |
|
8184 |
<description> |
|
8185 |
For the method indicated by <code>method</code>, |
|
8186 |
return the byte codes that implement the method. The number of |
|
8187 |
bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes |
|
8188 |
themselves are returned via <code>bytecodes_ptr</code>. |
|
8189 |
</description> |
|
8190 |
<origin>jvmdi</origin> |
|
8191 |
<capabilities> |
|
8192 |
<required id="can_get_bytecodes"></required> |
|
8193 |
</capabilities> |
|
8194 |
<parameters> |
|
8195 |
<param id="klass"> |
|
8196 |
<jclass method="method"/> |
|
8197 |
<description> |
|
8198 |
The class to query. |
|
8199 |
</description> |
|
8200 |
</param> |
|
8201 |
<param id="method"> |
|
8202 |
<jmethodID class="klass" native="error"/> |
|
8203 |
<description> |
|
8204 |
The method to query. |
|
8205 |
</description> |
|
8206 |
</param> |
|
8207 |
<param id="bytecode_count_ptr"> |
|
8208 |
<outptr><jint/></outptr> |
|
8209 |
<description> |
|
8210 |
On return, points to the length of the byte code array |
|
8211 |
</description> |
|
8212 |
</param> |
|
8213 |
<param id="bytecodes_ptr"> |
|
8214 |
<allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf> |
|
8215 |
<description> |
|
8216 |
On return, points to the pointer to the byte code array |
|
8217 |
</description> |
|
8218 |
</param> |
|
8219 |
</parameters> |
|
8220 |
<errors> |
|
8221 |
</errors> |
|
8222 |
</function> |
|
8223 |
||
8224 |
<function id="IsMethodNative" phase="start" num="76"> |
|
8225 |
<synopsis>Is Method Native</synopsis> |
|
8226 |
<description> |
|
8227 |
For the method indicated by <code>method</code>, return a |
|
8228 |
value indicating whether the method is native via <code>is_native_ptr</code> |
|
8229 |
</description> |
|
8230 |
<origin>jvmdi</origin> |
|
8231 |
<capabilities> |
|
8232 |
</capabilities> |
|
8233 |
<parameters> |
|
8234 |
<param id="klass"> |
|
8235 |
<jclass method="method"/> |
|
8236 |
<description> |
|
8237 |
The class to query. |
|
8238 |
</description> |
|
8239 |
</param> |
|
8240 |
<param id="method"> |
|
8241 |
<jmethodID class="klass"/> |
|
8242 |
<description> |
|
8243 |
The method to query. |
|
8244 |
</description> |
|
8245 |
</param> |
|
8246 |
<param id="is_native_ptr"> |
|
8247 |
<outptr><jboolean/></outptr> |
|
8248 |
<description> |
|
8249 |
On return, points to the boolean result of this function. |
|
8250 |
</description> |
|
8251 |
</param> |
|
8252 |
</parameters> |
|
8253 |
<errors> |
|
8254 |
</errors> |
|
8255 |
</function> |
|
8256 |
||
8257 |
<function id="IsMethodSynthetic" phase="start" num="77"> |
|
8258 |
<synopsis>Is Method Synthetic</synopsis> |
|
8259 |
<description> |
|
8260 |
For the method indicated by <code>method</code>, return a |
|
8261 |
value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>. |
|
8262 |
Synthetic methods are generated by the compiler but not present in the |
|
8263 |
original source code. |
|
8264 |
</description> |
|
8265 |
<origin>jvmdi</origin> |
|
8266 |
<capabilities> |
|
8267 |
<required id="can_get_synthetic_attribute"></required> |
|
8268 |
</capabilities> |
|
8269 |
<parameters> |
|
8270 |
<param id="klass"> |
|
8271 |
<jclass method="method"/> |
|
8272 |
<description> |
|
8273 |
The class to query. |
|
8274 |
</description> |
|
8275 |
</param> |
|
8276 |
<param id="method"> |
|
8277 |
<jmethodID class="klass"/> |
|
8278 |
<description> |
|
8279 |
The method to query. |
|
8280 |
</description> |
|
8281 |
</param> |
|
8282 |
<param id="is_synthetic_ptr"> |
|
8283 |
<outptr><jboolean/></outptr> |
|
8284 |
<description> |
|
8285 |
On return, points to the boolean result of this function. |
|
8286 |
</description> |
|
8287 |
</param> |
|
8288 |
</parameters> |
|
8289 |
<errors> |
|
8290 |
</errors> |
|
8291 |
</function> |
|
8292 |
||
8293 |
<function id="IsMethodObsolete" phase="start" num="91"> |
|
8294 |
<synopsis>Is Method Obsolete</synopsis> |
|
8295 |
<description> |
|
8296 |
Determine if a method ID refers to an |
|
8297 |
<internallink id="obsoleteMethods">obsolete</internallink> |
|
8298 |
method version. |
|
8299 |
</description> |
|
8300 |
<origin>jvmdi</origin> |
|
8301 |
<capabilities> |
|
8302 |
</capabilities> |
|
8303 |
<parameters> |
|
8304 |
<param id="klass"> |
|
8305 |
<jclass method="method"/> |
|
8306 |
<description> |
|
8307 |
The class to query. |
|
8308 |
</description> |
|
8309 |
</param> |
|
8310 |
<param id="method"> |
|
8311 |
<jmethodID class="klass"/> |
|
8312 |
<description> |
|
8313 |
The method ID to query. |
|
8314 |
</description> |
|
8315 |
</param> |
|
8316 |
<param id="is_obsolete_ptr"> |
|
8317 |
<outptr><jboolean/></outptr> |
|
8318 |
<description> |
|
8319 |
On return, points to the boolean result of this function. |
|
8320 |
</description> |
|
8321 |
</param> |
|
8322 |
</parameters> |
|
8323 |
<errors> |
|
8324 |
</errors> |
|
8325 |
</function> |
|
8326 |
||
8327 |
<function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1"> |
|
8328 |
<synopsis>Set Native Method Prefix</synopsis> |
|
8329 |
<description> |
|
8330 |
This function modifies the failure handling of |
|
8331 |
native method resolution by allowing retry |
|
8332 |
with a prefix applied to the name. |
|
8333 |
When used with the |
|
8334 |
<eventlink id="ClassFileLoadHook">ClassFileLoadHook |
|
8335 |
event</eventlink>, it enables native methods to be |
|
8336 |
<internallink id="bci">instrumented</internallink>. |
|
8337 |
<p/> |
|
8338 |
Since native methods cannot be directly instrumented |
|
8339 |
(they have no bytecodes), they must be wrapped with |
|
8340 |
a non-native method which can be instrumented. |
|
8341 |
For example, if we had: |
|
8342 |
<example> |
|
8343 |
native boolean foo(int x);</example> |
|
8344 |
<p/> |
|
8345 |
We could transform the class file (with the |
|
8346 |
ClassFileLoadHook event) so that this becomes: |
|
8347 |
<example> |
|
8348 |
boolean foo(int x) { |
|
8349 |
<i>... record entry to foo ...</i> |
|
8350 |
return wrapped_foo(x); |
|
8351 |
} |
|
8352 |
||
8353 |
native boolean wrapped_foo(int x);</example> |
|
8354 |
<p/> |
|
8355 |
Where foo becomes a wrapper for the actual native method |
|
8356 |
with the appended prefix "wrapped_". Note that |
|
8357 |
"wrapped_" would be a poor choice of prefix since it |
|
8358 |
might conceivably form the name of an existing method |
|
8359 |
thus something like "$$$MyAgentWrapped$$$_" would be |
|
8360 |
better but would make these examples less readable. |
|
8361 |
<p/> |
|
8362 |
The wrapper will allow data to be collected on the native |
|
8363 |
method call, but now the problem becomes linking up the |
|
8364 |
wrapped method with the native implementation. |
|
8365 |
That is, the method <code>wrapped_foo</code> needs to be |
|
8366 |
resolved to the native implementation of <code>foo</code>, |
|
8367 |
which might be: |
|
8368 |
<example> |
|
8369 |
Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example> |
|
8370 |
<p/> |
|
8371 |
This function allows the prefix to be specified and the |
|
8372 |
proper resolution to occur. |
|
8373 |
Specifically, when the standard resolution fails, the |
|
8374 |
resolution is retried taking the prefix into consideration. |
|
8375 |
There are two ways that resolution occurs, explicit |
|
8376 |
resolution with the JNI function <code>RegisterNatives</code> |
|
8377 |
and the normal automatic resolution. For |
|
8378 |
<code>RegisterNatives</code>, the VM will attempt this |
|
8379 |
association: |
|
8380 |
<example> |
|
8381 |
method(foo) -> nativeImplementation(foo)</example> |
|
8382 |
<p/> |
|
8383 |
When this fails, the resolution will be retried with |
|
8384 |
the specified prefix prepended to the method name, |
|
8385 |
yielding the correct resolution: |
|
8386 |
<example> |
|
8387 |
method(wrapped_foo) -> nativeImplementation(foo)</example> |
|
8388 |
<p/> |
|
8389 |
For automatic resolution, the VM will attempt: |
|
8390 |
<example> |
|
8391 |
method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example> |
|
8392 |
<p/> |
|
8393 |
When this fails, the resolution will be retried with |
|
8394 |
the specified prefix deleted from the implementation name, |
|
8395 |
yielding the correct resolution: |
|
8396 |
<example> |
|
8397 |
method(wrapped_foo) -> nativeImplementation(foo)</example> |
|
8398 |
<p/> |
|
8399 |
Note that since the prefix is only used when standard |
|
8400 |
resolution fails, native methods can be wrapped selectively. |
|
8401 |
<p/> |
|
8402 |
Since each <jvmti/> environment is independent and |
|
8403 |
can do its own transformation of the bytecodes, more |
|
8404 |
than one layer of wrappers may be applied. Thus each |
|
8405 |
environment needs its own prefix. Since transformations |
|
8406 |
are applied in order, the prefixes, if applied, will |
|
8407 |
be applied in the same order. |
|
8408 |
The order of transformation application is described in |
|
8409 |
the <eventlink id="ClassFileLoadHook"/> event. |
|
8410 |
Thus if three environments applied |
|
8411 |
wrappers, <code>foo</code> might become |
|
8412 |
<code>$env3_$env2_$env1_foo</code>. But if, say, |
|
8413 |
the second environment did not apply a wrapper to |
|
8414 |
<code>foo</code> it would be just |
|
8415 |
<code>$env3_$env1_foo</code>. To be able to |
|
8416 |
efficiently determine the sequence of prefixes, |
|
8417 |
an intermediate prefix is only applied if its non-native |
|
8418 |
wrapper exists. Thus, in the last example, even though |
|
8419 |
<code>$env1_foo</code> is not a native method, the |
|
8420 |
<code>$env1_</code> prefix is applied since |
|
8421 |
<code>$env1_foo</code> exists. |
|
8422 |
<p/> |
|
8423 |
Since the prefixes are used at resolution time |
|
8424 |
and since resolution may be arbitrarily delayed, a |
|
8425 |
native method prefix must remain set as long as there |
|
8426 |
are corresponding prefixed native methods. |
|
8427 |
</description> |
|
8428 |
<origin>new</origin> |
|
8429 |
<capabilities> |
|
8430 |
<required id="can_set_native_method_prefix"></required> |
|
8431 |
</capabilities> |
|
8432 |
<parameters> |
|
8433 |
<param id="prefix"> |
|
8434 |
<inbuf> |
|
8435 |
<char/> |
|
8436 |
<nullok> |
|
8437 |
any existing prefix in this environment is cancelled |
|
8438 |
</nullok> |
|
8439 |
</inbuf> |
|
8440 |
<description> |
|
8441 |
The prefix to apply, encoded as a |
|
8442 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
8443 |
</description> |
|
8444 |
</param> |
|
8445 |
</parameters> |
|
8446 |
<errors> |
|
8447 |
</errors> |
|
8448 |
</function> |
|
8449 |
||
8450 |
<function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1"> |
|
8451 |
<synopsis>Set Native Method Prefixes</synopsis> |
|
8452 |
<description> |
|
8453 |
For a normal agent, <functionlink id="SetNativeMethodPrefix"/> |
|
8454 |
will provide all needed native method prefixing. |
|
8455 |
For a meta-agent that performs multiple independent class |
|
8456 |
file transformations (for example as a proxy for another |
|
8457 |
layer of agents) this function allows each transformation |
|
8458 |
to have its own prefix. |
|
8459 |
The prefixes are applied in the order supplied and are |
|
8460 |
processed in the same manor as described for the |
|
8461 |
application of prefixes from multiple <jvmti/> environments |
|
8462 |
in <functionlink id="SetNativeMethodPrefix"/>. |
|
8463 |
<p/> |
|
8464 |
Any previous prefixes are replaced. Thus, calling this |
|
8465 |
function with a <paramlink id="prefix_count"/> of <code>0</code> |
|
8466 |
disables prefixing in this environment. |
|
8467 |
<p/> |
|
8468 |
<functionlink id="SetNativeMethodPrefix"/> and this function |
|
8469 |
are the two ways to set the prefixes. |
|
8470 |
Calling <code>SetNativeMethodPrefix</code> with |
|
8471 |
a prefix is the same as calling this function with |
|
8472 |
<paramlink id="prefix_count"/> of <code>1</code>. |
|
8473 |
Calling <code>SetNativeMethodPrefix</code> with |
|
8474 |
<code>NULL</code> is the same as calling this function with |
|
8475 |
<paramlink id="prefix_count"/> of <code>0</code>. |
|
8476 |
</description> |
|
8477 |
<origin>new</origin> |
|
8478 |
<capabilities> |
|
8479 |
<required id="can_set_native_method_prefix"></required> |
|
8480 |
</capabilities> |
|
8481 |
<parameters> |
|
8482 |
<param id="prefix_count"> |
|
8483 |
<jint min="0"/> |
|
8484 |
<description> |
|
8485 |
The number of prefixes to apply. |
|
8486 |
</description> |
|
8487 |
</param> |
|
8488 |
<param id="prefixes"> |
|
8489 |
<agentbuf> |
|
8490 |
<char/> |
|
8491 |
</agentbuf> |
|
8492 |
<description> |
|
8493 |
The prefixes to apply for this environment, each encoded as a |
|
8494 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
8495 |
</description> |
|
8496 |
</param> |
|
8497 |
</parameters> |
|
8498 |
<errors> |
|
8499 |
</errors> |
|
8500 |
</function> |
|
8501 |
||
8502 |
</category> |
|
8503 |
||
8504 |
<category id="RawMonitors" label="Raw Monitor"> |
|
8505 |
||
8506 |
<function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31"> |
|
8507 |
<synopsis>Create Raw Monitor</synopsis> |
|
8508 |
<description> |
|
8509 |
Create a raw monitor. |
|
8510 |
</description> |
|
8511 |
<origin>jvmdi</origin> |
|
8512 |
<capabilities> |
|
8513 |
</capabilities> |
|
8514 |
<parameters> |
|
8515 |
<param id="name"> |
|
8516 |
<inbuf><char/></inbuf> |
|
8517 |
<description> |
|
8518 |
A name to identify the monitor, encoded as a |
|
8519 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
8520 |
</description> |
|
8521 |
</param> |
|
8522 |
<param id="monitor_ptr"> |
|
8523 |
<outptr><jrawMonitorID/></outptr> |
|
8524 |
<description> |
|
8525 |
On return, points to the created monitor. |
|
8526 |
</description> |
|
8527 |
</param> |
|
8528 |
</parameters> |
|
8529 |
<errors> |
|
8530 |
</errors> |
|
8531 |
</function> |
|
8532 |
||
8533 |
<function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32"> |
|
8534 |
<synopsis>Destroy Raw Monitor</synopsis> |
|
8535 |
<description> |
|
8536 |
Destroy the raw monitor. |
|
8537 |
If the monitor being destroyed has been entered by this thread, it will be |
|
8538 |
exited before it is destroyed. |
|
8539 |
If the monitor being destroyed has been entered by another thread, |
|
8540 |
an error will be returned and the monitor will not be destroyed. |
|
8541 |
</description> |
|
8542 |
<origin>jvmdi</origin> |
|
8543 |
<capabilities> |
|
8544 |
</capabilities> |
|
8545 |
<parameters> |
|
8546 |
<param id="monitor"> |
|
8547 |
<jrawMonitorID/> |
|
8548 |
<description> |
|
8549 |
The monitor |
|
8550 |
</description> |
|
8551 |
</param> |
|
8552 |
</parameters> |
|
8553 |
<errors> |
|
8554 |
<error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> |
|
8555 |
Not monitor owner |
|
8556 |
</error> |
|
8557 |
</errors> |
|
8558 |
</function> |
|
8559 |
||
8560 |
<function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33"> |
|
8561 |
<synopsis>Raw Monitor Enter</synopsis> |
|
8562 |
<description> |
|
8563 |
Gain exclusive ownership of a raw monitor. |
|
8564 |
The same thread may enter a monitor more then once. |
|
8565 |
The thread must |
|
8566 |
<functionlink id="RawMonitorExit">exit</functionlink> |
|
8567 |
the monitor the same number of times as it is entered. |
|
8568 |
If a monitor is entered during <code>OnLoad</code> (before attached threads exist) |
|
8569 |
and has not exited when attached threads come into existence, the enter |
|
8570 |
is considered to have occurred on the main thread. |
|
8571 |
</description> |
|
8572 |
<origin>jvmdi</origin> |
|
8573 |
<capabilities> |
|
8574 |
</capabilities> |
|
8575 |
<parameters> |
|
8576 |
<param id="monitor"> |
|
8577 |
<jrawMonitorID/> |
|
8578 |
<description> |
|
8579 |
The monitor |
|
8580 |
</description> |
|
8581 |
</param> |
|
8582 |
</parameters> |
|
8583 |
<errors> |
|
8584 |
</errors> |
|
8585 |
</function> |
|
8586 |
||
8587 |
<function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34"> |
|
8588 |
<synopsis>Raw Monitor Exit</synopsis> |
|
8589 |
<description> |
|
8590 |
Release exclusive ownership of a raw monitor. |
|
8591 |
</description> |
|
8592 |
<origin>jvmdi</origin> |
|
8593 |
<capabilities> |
|
8594 |
</capabilities> |
|
8595 |
<parameters> |
|
8596 |
<param id="monitor"> |
|
8597 |
<jrawMonitorID/> |
|
8598 |
<description> |
|
8599 |
The monitor |
|
8600 |
</description> |
|
8601 |
</param> |
|
8602 |
</parameters> |
|
8603 |
<errors> |
|
8604 |
<error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> |
|
8605 |
Not monitor owner |
|
8606 |
</error> |
|
8607 |
</errors> |
|
8608 |
</function> |
|
8609 |
||
8610 |
<function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35"> |
|
8611 |
<synopsis>Raw Monitor Wait</synopsis> |
|
8612 |
<description> |
|
8613 |
Wait for notification of the raw monitor. |
|
8614 |
<p/> |
|
8615 |
Causes the current thread to wait until either another thread calls |
|
8616 |
<functionlink id="RawMonitorNotify"/> or |
|
8617 |
<functionlink id="RawMonitorNotifyAll"/> |
|
8618 |
for the specified raw monitor, or the specified |
|
8619 |
<paramlink id="millis">timeout</paramlink> |
|
8620 |
has elapsed. |
|
8621 |
</description> |
|
8622 |
<origin>jvmdi</origin> |
|
8623 |
<capabilities> |
|
8624 |
</capabilities> |
|
8625 |
<parameters> |
|
8626 |
<param id="monitor"> |
|
8627 |
<jrawMonitorID/> |
|
8628 |
<description> |
|
8629 |
The monitor |
|
8630 |
</description> |
|
8631 |
</param> |
|
8632 |
<param id="millis"> |
|
8633 |
<jlong/> |
|
8634 |
<description> |
|
8635 |
The timeout, in milliseconds. If the timeout is |
|
8636 |
zero, then real time is not taken into consideration |
|
8637 |
and the thread simply waits until notified. |
|
8638 |
</description> |
|
8639 |
</param> |
|
8640 |
</parameters> |
|
8641 |
<errors> |
|
8642 |
<error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> |
|
8643 |
Not monitor owner |
|
8644 |
</error> |
|
8645 |
<error id="JVMTI_ERROR_INTERRUPT"> |
|
8646 |
Wait was interrupted, try again |
|
8647 |
</error> |
|
8648 |
</errors> |
|
8649 |
</function> |
|
8650 |
||
8651 |
<function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36"> |
|
8652 |
<synopsis>Raw Monitor Notify</synopsis> |
|
8653 |
<description> |
|
8654 |
Notify a single thread waiting on the raw monitor. |
|
8655 |
</description> |
|
8656 |
<origin>jvmdi</origin> |
|
8657 |
<capabilities> |
|
8658 |
</capabilities> |
|
8659 |
<parameters> |
|
8660 |
<param id="monitor"> |
|
8661 |
<jrawMonitorID/> |
|
8662 |
<description> |
|
8663 |
The monitor |
|
8664 |
</description> |
|
8665 |
</param> |
|
8666 |
</parameters> |
|
8667 |
<errors> |
|
8668 |
<error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> |
|
8669 |
Not monitor owner |
|
8670 |
</error> |
|
8671 |
</errors> |
|
8672 |
</function> |
|
8673 |
||
8674 |
<function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37"> |
|
8675 |
<synopsis>Raw Monitor Notify All</synopsis> |
|
8676 |
<description> |
|
8677 |
Notify all threads waiting on the raw monitor. |
|
8678 |
</description> |
|
8679 |
<origin>jvmdi</origin> |
|
8680 |
<capabilities> |
|
8681 |
</capabilities> |
|
8682 |
<parameters> |
|
8683 |
<param id="monitor"> |
|
8684 |
<jrawMonitorID/> |
|
8685 |
<description> |
|
8686 |
The monitor |
|
8687 |
</description> |
|
8688 |
</param> |
|
8689 |
</parameters> |
|
8690 |
<errors> |
|
8691 |
<error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> |
|
8692 |
Not monitor owner |
|
8693 |
</error> |
|
8694 |
</errors> |
|
8695 |
</function> |
|
8696 |
||
8697 |
<elide> |
|
8698 |
<function id="GetRawMonitorUse" num="118"> |
|
8699 |
<synopsis>Get Raw Monitor Use</synopsis> |
|
8700 |
<description> |
|
8701 |
The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure |
|
8702 |
are filled in with information about usage of the raw monitor. |
|
8703 |
</description> |
|
8704 |
<origin>new</origin> |
|
8705 |
<capabilities> |
|
8706 |
<required id="can_get_raw_monitor_usage"></required> |
|
8707 |
</capabilities> |
|
8708 |
<parameters> |
|
8709 |
<param id="monitor"> |
|
8710 |
<jrawMonitorID/> |
|
8711 |
<description> |
|
8712 |
the raw monitor to query. |
|
8713 |
</description> |
|
8714 |
</param> |
|
8715 |
<param id="info_ptr"> |
|
8716 |
<outptr><struct>jvmtiMonitorUsage</struct></outptr> |
|
8717 |
<description> |
|
8718 |
On return, filled with monitor information for the |
|
8719 |
specified raw monitor. |
|
8720 |
</description> |
|
8721 |
</param> |
|
8722 |
</parameters> |
|
8723 |
<errors> |
|
8724 |
</errors> |
|
8725 |
</function> |
|
8726 |
||
8727 |
<function id="GetRawMonitors" num="119"> |
|
8728 |
<synopsis>Get Raw Monitors</synopsis> |
|
8729 |
<description> |
|
8730 |
Return the list of raw monitors. |
|
8731 |
<p/> |
|
8732 |
Note: details about each monitor can be examined with |
|
8733 |
<functionlink id="GetRawMonitorUse"></functionlink>. |
|
8734 |
</description> |
|
8735 |
<origin>new</origin> |
|
8736 |
<capabilities> |
|
8737 |
<required id="can_get_raw_monitor_usage"></required> |
|
8738 |
</capabilities> |
|
8739 |
<parameters> |
|
8740 |
<param id="monitorCnt"> |
|
8741 |
<outptr><jint/></outptr> |
|
8742 |
<description> |
|
8743 |
On return, pointer to the number |
|
8744 |
of monitors returned in <code>monitors_ptr</code>. |
|
8745 |
</description> |
|
8746 |
</param> |
|
8747 |
<param id="monitors_ptr"> |
|
8748 |
<allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf> |
|
8749 |
<description> |
|
8750 |
On return, pointer to the monitor list. |
|
8751 |
</description> |
|
8752 |
</param> |
|
8753 |
</parameters> |
|
8754 |
<errors> |
|
8755 |
</errors> |
|
8756 |
</function> |
|
8757 |
</elide> |
|
8758 |
</category> |
|
8759 |
||
8760 |
<category id="jniIntercept" label="JNI Function Interception"> |
|
8761 |
||
8762 |
<intro> |
|
8763 |
Provides the ability to intercept and resend |
|
8764 |
Java Native Interface (JNI) function calls |
|
8765 |
by manipulating the JNI function table. |
|
14287 | 8766 |
See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI |
1 | 8767 |
Functions</externallink> in the <i>Java Native Interface Specification</i>. |
8768 |
<p/> |
|
8769 |
The following example illustrates intercepting the |
|
8770 |
<code>NewGlobalRef</code> JNI call in order to count reference |
|
8771 |
creation. |
|
8772 |
<example> |
|
8773 |
JNIEnv original_jni_Functions; |
|
8774 |
JNIEnv redirected_jni_Functions; |
|
8775 |
int my_global_ref_count = 0; |
|
8776 |
||
8777 |
jobject |
|
8778 |
MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) { |
|
8779 |
++my_global_ref_count; |
|
8780 |
return originalJNIFunctions->NewGlobalRef(env, lobj); |
|
8781 |
} |
|
8782 |
||
8783 |
void |
|
8784 |
myInit() { |
|
8785 |
jvmtiError err; |
|
8786 |
||
8787 |
err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions); |
|
8788 |
if (err != JVMTI_ERROR_NONE) { |
|
8789 |
die(); |
|
8790 |
} |
|
8791 |
err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions); |
|
8792 |
if (err != JVMTI_ERROR_NONE) { |
|
8793 |
die(); |
|
8794 |
} |
|
8795 |
redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef; |
|
8796 |
err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions); |
|
8797 |
if (err != JVMTI_ERROR_NONE) { |
|
8798 |
die(); |
|
8799 |
} |
|
8800 |
} |
|
8801 |
</example> |
|
8802 |
Sometime after <code>myInit</code> is called the user's JNI |
|
8803 |
code is executed which makes the call to create a new global |
|
8804 |
reference. Instead of going to the normal JNI implementation |
|
8805 |
the call goes to <code>myNewGlobalRef</code>. Note that a |
|
8806 |
copy of the original function table is kept so that the normal |
|
8807 |
JNI function can be called after the data is collected. |
|
8808 |
Note also that any JNI functions which are not overwritten |
|
8809 |
will behave normally. |
|
8810 |
<todo> |
|
8811 |
check that the example compiles and executes. |
|
8812 |
</todo> |
|
8813 |
</intro> |
|
8814 |
||
8815 |
<function id="SetJNIFunctionTable" phase="start" num="120"> |
|
8816 |
<synopsis>Set JNI Function Table</synopsis> |
|
8817 |
<description> |
|
8818 |
Set the JNI function table |
|
8819 |
in all current and future JNI environments. |
|
8820 |
As a result, all future JNI calls are directed to the specified functions. |
|
8821 |
Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the |
|
8822 |
function table to pass to this function. |
|
8823 |
For this function to take effect the the updated table entries must be |
|
8824 |
used by the JNI clients. |
|
8825 |
Since the table is defined <code>const</code> some compilers may optimize |
|
8826 |
away the access to the table, thus preventing this function from taking |
|
8827 |
effect. |
|
8828 |
The table is copied--changes to the local copy of the |
|
8829 |
table have no effect. |
|
8830 |
This function affects only the function table, all other aspects of the environment are |
|
8831 |
unaffected. |
|
8832 |
See the examples <internallink id="jniIntercept">above</internallink>. |
|
8833 |
</description> |
|
8834 |
<origin>new</origin> |
|
8835 |
<capabilities> |
|
8836 |
</capabilities> |
|
8837 |
<parameters> |
|
8838 |
<param id="function_table"> |
|
8839 |
<inptr> |
|
8840 |
<struct>jniNativeInterface</struct> |
|
8841 |
</inptr> |
|
8842 |
<description> |
|
8843 |
Points to the new JNI function table. |
|
8844 |
</description> |
|
8845 |
</param> |
|
8846 |
</parameters> |
|
8847 |
<errors> |
|
8848 |
</errors> |
|
8849 |
</function> |
|
8850 |
||
8851 |
<function id="GetJNIFunctionTable" phase="start" num="121"> |
|
8852 |
<synopsis>Get JNI Function Table</synopsis> |
|
8853 |
<description> |
|
8854 |
Get the JNI function table. |
|
8855 |
The JNI function table is copied into allocated memory. |
|
8856 |
If <functionlink id="SetJNIFunctionTable"></functionlink> |
|
8857 |
has been called, the modified (not the original) function |
|
8858 |
table is returned. |
|
8859 |
Only the function table is copied, no other aspects of the environment |
|
8860 |
are copied. |
|
8861 |
See the examples <internallink id="jniIntercept">above</internallink>. |
|
8862 |
</description> |
|
8863 |
<origin>new</origin> |
|
8864 |
<capabilities> |
|
8865 |
</capabilities> |
|
8866 |
<parameters> |
|
8867 |
<param id="function_table"> |
|
8868 |
<allocbuf> |
|
8869 |
<struct>jniNativeInterface</struct> |
|
8870 |
</allocbuf> |
|
8871 |
<description> |
|
8872 |
On return, <code>*function_table</code> |
|
8873 |
points a newly allocated copy of the JNI function table. |
|
8874 |
</description> |
|
8875 |
</param> |
|
8876 |
</parameters> |
|
8877 |
<errors> |
|
8878 |
</errors> |
|
8879 |
</function> |
|
8880 |
||
8881 |
</category> |
|
8882 |
||
8883 |
<category id="eventManagement" label="Event Management"> |
|
8884 |
||
8885 |
<function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122"> |
|
8886 |
<synopsis>Set Event Callbacks</synopsis> |
|
8887 |
<description> |
|
8888 |
Set the functions to be called for each event. |
|
8889 |
The callbacks are specified by supplying a replacement function table. |
|
8890 |
The function table is copied--changes to the local copy of the |
|
8891 |
table have no effect. |
|
8892 |
This is an atomic action, all callbacks are set at once. |
|
8893 |
No events are sent before this function is called. |
|
8894 |
When an entry is <code>NULL</code> or when the event is beyond |
|
8895 |
<paramlink id="size_of_callbacks"></paramlink> no event is sent. |
|
8896 |
Details on events are |
|
8897 |
described <internallink id="EventSection">later</internallink> in this document. |
|
8898 |
An event must be enabled and have a callback in order to be |
|
8899 |
sent--the order in which this function and |
|
8900 |
<functionlink id="SetEventNotificationMode"></functionlink> |
|
8901 |
are called does not affect the result. |
|
8902 |
</description> |
|
8903 |
<origin>new</origin> |
|
8904 |
<capabilities> |
|
8905 |
</capabilities> |
|
8906 |
<parameters> |
|
8907 |
<param id="callbacks"> |
|
8908 |
<inptr> |
|
8909 |
<struct>jvmtiEventCallbacks</struct> |
|
8910 |
<nullok>remove the existing callbacks</nullok> |
|
8911 |
</inptr> |
|
8912 |
<description> |
|
8913 |
The new event callbacks. |
|
8914 |
</description> |
|
8915 |
</param> |
|
8916 |
<param id="size_of_callbacks"> |
|
8917 |
<jint min="0"/> |
|
8918 |
<description> |
|
8919 |
<code>sizeof(jvmtiEventCallbacks)</code>--for version |
|
8920 |
compatibility. |
|
8921 |
</description> |
|
8922 |
</param> |
|
8923 |
</parameters> |
|
8924 |
<errors> |
|
8925 |
</errors> |
|
8926 |
</function> |
|
8927 |
||
8928 |
<function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2"> |
|
8929 |
<synopsis>Set Event Notification Mode</synopsis> |
|
8930 |
<description> |
|
8931 |
Control the generation of events. |
|
8932 |
<constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum"> |
|
8933 |
<constant id="JVMTI_ENABLE" num="1"> |
|
8934 |
If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, |
|
8935 |
the event <paramlink id="event_type"></paramlink> will be enabled |
|
8936 |
</constant> |
|
8937 |
<constant id="JVMTI_DISABLE" num="0"> |
|
8938 |
If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, |
|
8939 |
the event <paramlink id="event_type"></paramlink> will be disabled |
|
8940 |
</constant> |
|
8941 |
</constants> |
|
8942 |
If <code>thread</code> is <code>NULL</code>, |
|
8943 |
the event is enabled or disabled globally; otherwise, it is |
|
8944 |
enabled or disabled for a particular thread. |
|
8945 |
An event is generated for |
|
8946 |
a particular thread if it is enabled either at the thread or global |
|
8947 |
levels. |
|
8948 |
<p/> |
|
8949 |
See <internallink id="EventIndex">below</internallink> for information on specific events. |
|
8950 |
<p/> |
|
8951 |
The following events cannot be controlled at the thread |
|
8952 |
level through this function. |
|
8953 |
<ul> |
|
8954 |
<li><eventlink id="VMInit"></eventlink></li> |
|
8955 |
<li><eventlink id="VMStart"></eventlink></li> |
|
8956 |
<li><eventlink id="VMDeath"></eventlink></li> |
|
8957 |
<li><eventlink id="ThreadStart"></eventlink></li> |
|
8958 |
<li><eventlink id="CompiledMethodLoad"></eventlink></li> |
|
8959 |
<li><eventlink id="CompiledMethodUnload"></eventlink></li> |
|
8960 |
<li><eventlink id="DynamicCodeGenerated"></eventlink></li> |
|
8961 |
<li><eventlink id="DataDumpRequest"></eventlink></li> |
|
8962 |
</ul> |
|
8963 |
<p/> |
|
8964 |
Initially, no events are enabled at either the thread level |
|
8965 |
or the global level. |
|
8966 |
<p/> |
|
8967 |
Any needed capabilities (see Event Enabling Capabilities below) must be possessed |
|
8968 |
before calling this function. |
|
8969 |
<p/> |
|
8970 |
Details on events are |
|
8971 |
described <internallink id="EventSection">below</internallink>. |
|
8972 |
</description> |
|
8973 |
<origin>jvmdiClone</origin> |
|
8974 |
<eventcapabilities></eventcapabilities> |
|
8975 |
<parameters> |
|
8976 |
<param id="mode"> |
|
8977 |
<enum>jvmtiEventMode</enum> |
|
8978 |
<description> |
|
8979 |
<code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code> |
|
8980 |
</description> |
|
8981 |
</param> |
|
8982 |
<param id="event_type"> |
|
8983 |
<enum>jvmtiEvent</enum> |
|
8984 |
<description> |
|
8985 |
the event to control |
|
8986 |
</description> |
|
8987 |
</param> |
|
8988 |
<param id="event_thread"> |
|
8989 |
<ptrtype> |
|
8990 |
<jthread impl="noconvert"/> |
|
8991 |
<nullok>event is controlled at the global level</nullok> |
|
8992 |
</ptrtype> |
|
8993 |
<description> |
|
8994 |
The thread to control |
|
8995 |
</description> |
|
8996 |
</param> |
|
8997 |
<param id="..."> |
|
8998 |
<varargs/> |
|
8999 |
<description> |
|
9000 |
for future expansion |
|
9001 |
</description> |
|
9002 |
</param> |
|
9003 |
</parameters> |
|
9004 |
<errors> |
|
9005 |
<error id="JVMTI_ERROR_INVALID_THREAD"> |
|
9006 |
<paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread. |
|
9007 |
</error> |
|
9008 |
<error id="JVMTI_ERROR_THREAD_NOT_ALIVE"> |
|
9009 |
<paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead). |
|
9010 |
</error> |
|
9011 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
9012 |
thread level control was attempted on events which do not |
|
9013 |
permit thread level control. |
|
9014 |
</error> |
|
9015 |
<error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> |
|
9016 |
The Required Event Enabling Capability is not possessed. |
|
9017 |
</error> |
|
9018 |
</errors> |
|
9019 |
</function> |
|
9020 |
||
9021 |
<function id="GenerateEvents" num="123"> |
|
9022 |
<synopsis>Generate Events</synopsis> |
|
9023 |
<description> |
|
9024 |
Generate events to represent the current state of the VM. |
|
9025 |
For example, if <paramlink id="event_type"/> is |
|
9026 |
<code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>, |
|
9027 |
a <eventlink id="CompiledMethodLoad"></eventlink> event will be |
|
9028 |
sent for each currently compiled method. |
|
9029 |
Methods that were loaded and now have been unloaded are not sent. |
|
9030 |
The history of what events have previously been sent does not |
|
9031 |
effect what events are sent by this function--for example, |
|
9032 |
all currently compiled methods |
|
9033 |
will be sent each time this function is called. |
|
9034 |
<p/> |
|
9035 |
This function is useful when |
|
9036 |
events may have been missed due to the agent attaching after program |
|
9037 |
execution begins; this function generates the missed events. |
|
9038 |
<p/> |
|
9039 |
Attempts to execute Java programming language code or |
|
9040 |
JNI functions may be paused until this function returns - |
|
9041 |
so neither should be called from the thread sending the event. |
|
9042 |
This function returns only after the missed events have been |
|
9043 |
sent, processed and have returned. |
|
9044 |
The event may be sent on a different thread than the thread |
|
9045 |
on which the event occurred. |
|
9046 |
The callback for the event must be set with |
|
9047 |
<functionlink id="SetEventCallbacks"></functionlink> |
|
9048 |
and the event must be enabled with |
|
9049 |
<functionlink id="SetEventNotificationMode"></functionlink> |
|
9050 |
or the events will not occur. |
|
9051 |
If the VM no longer has the information to generate some or |
|
9052 |
all of the requested events, the events are simply not sent - |
|
9053 |
no error is returned. |
|
9054 |
<p/> |
|
9055 |
Only the following events are supported: |
|
9056 |
<ul> |
|
9057 |
<li><eventlink id="CompiledMethodLoad"></eventlink></li> |
|
9058 |
<li><eventlink id="DynamicCodeGenerated"></eventlink></li> |
|
9059 |
</ul> |
|
9060 |
</description> |
|
9061 |
<origin>new</origin> |
|
9062 |
<capabilities> |
|
9063 |
<capability id="can_generate_compiled_method_load_events"></capability> |
|
9064 |
</capabilities> |
|
9065 |
<parameters> |
|
9066 |
<param id="event_type"> |
|
9067 |
<enum>jvmtiEvent</enum> |
|
9068 |
<description> |
|
9069 |
The type of event to generate. Must be one of these: |
|
9070 |
<ul> |
|
9071 |
<li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li> |
|
9072 |
<li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li> |
|
9073 |
</ul> |
|
9074 |
</description> |
|
9075 |
</param> |
|
9076 |
</parameters> |
|
9077 |
<errors> |
|
9078 |
<error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> |
|
9079 |
<paramlink id="event_type"/> is |
|
9080 |
<eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> |
|
9081 |
and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink> |
|
9082 |
is <code>false</code>. |
|
9083 |
</error> |
|
9084 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
9085 |
<paramlink id="event_type"/> is other than |
|
9086 |
<eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink> |
|
9087 |
or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>. |
|
9088 |
</error> |
|
9089 |
</errors> |
|
9090 |
</function> |
|
9091 |
||
9092 |
</category> |
|
9093 |
||
9094 |
<category id="extension" label="Extension Mechanism"> |
|
9095 |
||
9096 |
<intro> |
|
9097 |
These functions |
|
9098 |
allow a <jvmti/> implementation to provide functions and events |
|
9099 |
beyond those defined in this specification. |
|
9100 |
<p/> |
|
9101 |
Both extension functions and extension events have parameters |
|
9102 |
each of which has a 'type' and 'kind' chosen from the following tables: |
|
9103 |
||
9104 |
<constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum"> |
|
9105 |
<constant id="JVMTI_TYPE_JBYTE" num="101"> |
|
9106 |
Java programming language primitive type - <code>byte</code>. |
|
9107 |
JNI type <code>jbyte</code>. |
|
9108 |
</constant> |
|
9109 |
<constant id="JVMTI_TYPE_JCHAR" num="102"> |
|
9110 |
Java programming language primitive type - <code>char</code>. |
|
9111 |
JNI type <code>jchar</code>. |
|
9112 |
</constant> |
|
9113 |
<constant id="JVMTI_TYPE_JSHORT" num="103"> |
|
9114 |
Java programming language primitive type - <code>short</code>. |
|
9115 |
JNI type <code>jshort</code>. |
|
9116 |
</constant> |
|
9117 |
<constant id="JVMTI_TYPE_JINT" num="104"> |
|
9118 |
Java programming language primitive type - <code>int</code>. |
|
9119 |
JNI type <datalink id="jint"></datalink>. |
|
9120 |
</constant> |
|
9121 |
<constant id="JVMTI_TYPE_JLONG" num="105"> |
|
9122 |
Java programming language primitive type - <code>long</code>. |
|
9123 |
JNI type <datalink id="jlong"></datalink>. |
|
9124 |
</constant> |
|
9125 |
<constant id="JVMTI_TYPE_JFLOAT" num="106"> |
|
9126 |
Java programming language primitive type - <code>float</code>. |
|
9127 |
JNI type <datalink id="jfloat"></datalink>. |
|
9128 |
</constant> |
|
9129 |
<constant id="JVMTI_TYPE_JDOUBLE" num="107"> |
|
9130 |
Java programming language primitive type - <code>double</code>. |
|
9131 |
JNI type <datalink id="jdouble"></datalink>. |
|
9132 |
</constant> |
|
9133 |
<constant id="JVMTI_TYPE_JBOOLEAN" num="108"> |
|
9134 |
Java programming language primitive type - <code>boolean</code>. |
|
9135 |
JNI type <datalink id="jboolean"></datalink>. |
|
9136 |
</constant> |
|
9137 |
<constant id="JVMTI_TYPE_JOBJECT" num="109"> |
|
9138 |
Java programming language object type - <code>java.lang.Object</code>. |
|
9139 |
JNI type <datalink id="jobject"></datalink>. |
|
9140 |
Returned values are JNI local references and must be managed. |
|
9141 |
</constant> |
|
9142 |
<constant id="JVMTI_TYPE_JTHREAD" num="110"> |
|
9143 |
Java programming language object type - <code>java.lang.Thread</code>. |
|
9144 |
<jvmti/> type <datalink id="jthread"></datalink>. |
|
9145 |
Returned values are JNI local references and must be managed. |
|
9146 |
</constant> |
|
9147 |
<constant id="JVMTI_TYPE_JCLASS" num="111"> |
|
9148 |
Java programming language object type - <code>java.lang.Class</code>. |
|
9149 |
JNI type <datalink id="jclass"></datalink>. |
|
9150 |
Returned values are JNI local references and must be managed. |
|
9151 |
</constant> |
|
9152 |
<constant id="JVMTI_TYPE_JVALUE" num="112"> |
|
9153 |
Union of all Java programming language primitive and object types - |
|
9154 |
JNI type <datalink id="jvalue"></datalink>. |
|
9155 |
Returned values which represent object types are JNI local references and must be managed. |
|
9156 |
</constant> |
|
9157 |
<constant id="JVMTI_TYPE_JFIELDID" num="113"> |
|
9158 |
Java programming language field identifier - |
|
9159 |
JNI type <datalink id="jfieldID"></datalink>. |
|
9160 |
</constant> |
|
9161 |
<constant id="JVMTI_TYPE_JMETHODID" num="114"> |
|
9162 |
Java programming language method identifier - |
|
9163 |
JNI type <datalink id="jmethodID"></datalink>. |
|
9164 |
</constant> |
|
9165 |
<constant id="JVMTI_TYPE_CCHAR" num="115"> |
|
9166 |
C programming language type - <code>char</code>. |
|
9167 |
</constant> |
|
9168 |
<constant id="JVMTI_TYPE_CVOID" num="116"> |
|
9169 |
C programming language type - <code>void</code>. |
|
9170 |
</constant> |
|
9171 |
<constant id="JVMTI_TYPE_JNIENV" num="117"> |
|
9172 |
JNI environment - <code>JNIEnv</code>. |
|
9173 |
Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type. |
|
9174 |
</constant> |
|
9175 |
</constants> |
|
9176 |
||
9177 |
<constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum"> |
|
9178 |
<constant id="JVMTI_KIND_IN" num="91"> |
|
9179 |
Ingoing argument - <code>foo</code>. |
|
9180 |
</constant> |
|
9181 |
<constant id="JVMTI_KIND_IN_PTR" num="92"> |
|
9182 |
Ingoing pointer argument - <code>const foo*</code>. |
|
9183 |
</constant> |
|
9184 |
<constant id="JVMTI_KIND_IN_BUF" num="93"> |
|
9185 |
Ingoing array argument - <code>const foo*</code>. |
|
9186 |
</constant> |
|
9187 |
<constant id="JVMTI_KIND_ALLOC_BUF" num="94"> |
|
9188 |
Outgoing allocated array argument - <code>foo**</code>. |
|
9189 |
Free with <code>Deallocate</code>. |
|
9190 |
</constant> |
|
9191 |
<constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95"> |
|
9192 |
Outgoing allocated array of allocated arrays argument - <code>foo***</code>. |
|
9193 |
Free with <code>Deallocate</code>. |
|
9194 |
</constant> |
|
9195 |
<constant id="JVMTI_KIND_OUT" num="96"> |
|
9196 |
Outgoing argument - <code>foo*</code>. |
|
9197 |
</constant> |
|
9198 |
<constant id="JVMTI_KIND_OUT_BUF" num="97"> |
|
9199 |
Outgoing array argument (pre-allocated by agent) - <code>foo*</code>. |
|
9200 |
Do not <code>Deallocate</code>. |
|
9201 |
</constant> |
|
9202 |
</constants> |
|
9203 |
||
9204 |
</intro> |
|
9205 |
||
9206 |
<typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info"> |
|
9207 |
<field id="name"> |
|
9208 |
<allocfieldbuf><char/></allocfieldbuf> |
|
9209 |
<description> |
|
9210 |
The parameter name, encoded as a |
|
9211 |
<internallink id="mUTF">modified UTF-8</internallink> string |
|
9212 |
</description> |
|
9213 |
</field> |
|
9214 |
<field id="kind"> |
|
9215 |
<enum>jvmtiParamKind</enum> |
|
9216 |
<description> |
|
9217 |
The kind of the parameter - type modifiers |
|
9218 |
</description> |
|
9219 |
</field> |
|
9220 |
<field id="base_type"> |
|
9221 |
<enum>jvmtiParamTypes</enum> |
|
9222 |
<description> |
|
9223 |
The base type of the parameter - modified by <code>kind</code> |
|
9224 |
</description> |
|
9225 |
</field> |
|
9226 |
<field id="null_ok"> |
|
9227 |
<jboolean/> |
|
9228 |
<description> |
|
9229 |
Is a <code>NULL</code> argument permitted? Applies only to pointer and object types. |
|
9230 |
</description> |
|
9231 |
</field> |
|
9232 |
</typedef> |
|
9233 |
||
9234 |
<callback id="jvmtiExtensionFunction"> |
|
9235 |
<enum>jvmtiError</enum> |
|
9236 |
<synopsis>Extension Function</synopsis> |
|
9237 |
<description> |
|
9238 |
This is the implementation-specific extension function. |
|
9239 |
</description> |
|
9240 |
<parameters> |
|
9241 |
<param id="jvmti_env"> |
|
9242 |
<outptr> |
|
9243 |
<struct>jvmtiEnv</struct> |
|
9244 |
</outptr> |
|
9245 |
<description> |
|
9246 |
The <jvmti/> environment is the only fixed parameter for extension functions. |
|
9247 |
</description> |
|
9248 |
</param> |
|
9249 |
<param id="..."> |
|
9250 |
<varargs/> |
|
9251 |
<description> |
|
9252 |
The extension function-specific parameters |
|
9253 |
</description> |
|
9254 |
</param> |
|
9255 |
</parameters> |
|
9256 |
</callback> |
|
9257 |
||
9258 |
<function id="GetExtensionFunctions" phase="onload" num="124"> |
|
9259 |
<synopsis>Get Extension Functions</synopsis> |
|
9260 |
||
9261 |
<typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info"> |
|
9262 |
<field id="func"> |
|
9263 |
<ptrtype> |
|
9264 |
<struct>jvmtiExtensionFunction</struct> |
|
9265 |
</ptrtype> |
|
9266 |
<description> |
|
9267 |
The actual function to call |
|
9268 |
</description> |
|
9269 |
</field> |
|
9270 |
<field id="id"> |
|
9271 |
<allocfieldbuf><char/></allocfieldbuf> |
|
9272 |
<description> |
|
9273 |
The identifier for the extension function, encoded as a |
|
9274 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
9275 |
Uses package name conventions. |
|
9276 |
For example, <code>com.sun.hotspot.bar</code> |
|
9277 |
</description> |
|
9278 |
</field> |
|
9279 |
<field id="short_description"> |
|
9280 |
<allocfieldbuf><char/></allocfieldbuf> |
|
9281 |
<description> |
|
9282 |
A one sentence description of the function, encoded as a |
|
9283 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
9284 |
</description> |
|
9285 |
</field> |
|
9286 |
<field id="param_count"> |
|
9287 |
<jint/> |
|
9288 |
<description> |
|
9289 |
The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> |
|
9290 |
</description> |
|
9291 |
</field> |
|
9292 |
<field id="params"> |
|
9293 |
<allocfieldbuf outcount="param_count"> |
|
9294 |
<struct>jvmtiParamInfo</struct> |
|
9295 |
</allocfieldbuf> |
|
9296 |
<description> |
|
9297 |
Array of |
|
9298 |
<fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> |
|
9299 |
parameters (<code>jvmtiEnv *jvmti_env</code> excluded) |
|
9300 |
</description> |
|
9301 |
</field> |
|
9302 |
<field id="error_count"> |
|
9303 |
<jint/> |
|
9304 |
<description> |
|
9305 |
The number of possible error returns (excluding universal errors) |
|
9306 |
</description> |
|
9307 |
</field> |
|
9308 |
<field id="errors"> |
|
9309 |
<allocfieldbuf outcount="error_count"> |
|
9310 |
<enum>jvmtiError</enum> |
|
9311 |
</allocfieldbuf> |
|
9312 |
<description> |
|
9313 |
Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink> |
|
9314 |
possible errors |
|
9315 |
</description> |
|
9316 |
</field> |
|
9317 |
</typedef> |
|
9318 |
||
9319 |
<description> |
|
9320 |
Returns the set of extension functions. |
|
9321 |
</description> |
|
9322 |
<origin>new</origin> |
|
9323 |
<capabilities> |
|
9324 |
</capabilities> |
|
9325 |
<parameters> |
|
9326 |
<param id="extension_count_ptr"> |
|
9327 |
<outptr><jint/></outptr> |
|
9328 |
<description> |
|
9329 |
On return, points to the number of extension functions |
|
9330 |
</description> |
|
9331 |
</param> |
|
9332 |
<param id="extensions"> |
|
9333 |
<allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf> |
|
9334 |
<description> |
|
9335 |
Returns an array of extension function info, one per function |
|
9336 |
</description> |
|
9337 |
</param> |
|
9338 |
</parameters> |
|
9339 |
<errors> |
|
9340 |
</errors> |
|
9341 |
</function> |
|
9342 |
||
9343 |
<function id="GetExtensionEvents" phase="onload" num="125"> |
|
9344 |
<synopsis>Get Extension Events</synopsis> |
|
9345 |
||
9346 |
<typedef id="jvmtiExtensionEventInfo" label="Extension Event Info"> |
|
9347 |
<field id="extension_event_index"> |
|
9348 |
<jint/> |
|
9349 |
<description> |
|
9350 |
The identifying index of the event |
|
9351 |
</description> |
|
9352 |
</field> |
|
9353 |
<field id="id"> |
|
9354 |
<allocfieldbuf><char/></allocfieldbuf> |
|
9355 |
<description> |
|
9356 |
The identifier for the extension event, encoded as a |
|
9357 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
9358 |
Uses package name conventions. |
|
9359 |
For example, <code>com.sun.hotspot.bar</code> |
|
9360 |
</description> |
|
9361 |
</field> |
|
9362 |
<field id="short_description"> |
|
9363 |
<allocfieldbuf><char/></allocfieldbuf> |
|
9364 |
<description> |
|
9365 |
A one sentence description of the event, encoded as a |
|
9366 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
9367 |
</description> |
|
9368 |
</field> |
|
9369 |
<field id="param_count"> |
|
9370 |
<jint/> |
|
9371 |
<description> |
|
9372 |
The number of parameters excluding <code>jvmtiEnv *jvmti_env</code> |
|
9373 |
</description> |
|
9374 |
</field> |
|
9375 |
<field id="params"> |
|
9376 |
<allocfieldbuf outcount="param_count"> |
|
9377 |
<struct>jvmtiParamInfo</struct> |
|
9378 |
</allocfieldbuf> |
|
9379 |
<description> |
|
9380 |
Array of |
|
9381 |
<fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink> |
|
9382 |
parameters (<code>jvmtiEnv *jvmti_env</code> excluded) |
|
9383 |
</description> |
|
9384 |
</field> |
|
9385 |
</typedef> |
|
9386 |
||
9387 |
<description> |
|
9388 |
Returns the set of extension events. |
|
9389 |
</description> |
|
9390 |
<origin>new</origin> |
|
9391 |
<capabilities> |
|
9392 |
</capabilities> |
|
9393 |
<parameters> |
|
9394 |
<param id="extension_count_ptr"> |
|
9395 |
<outptr><jint/></outptr> |
|
9396 |
<description> |
|
9397 |
On return, points to the number of extension events |
|
9398 |
</description> |
|
9399 |
</param> |
|
9400 |
<param id="extensions"> |
|
9401 |
<allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf> |
|
9402 |
<description> |
|
9403 |
Returns an array of extension event info, one per event |
|
9404 |
</description> |
|
9405 |
</param> |
|
9406 |
</parameters> |
|
9407 |
<errors> |
|
9408 |
</errors> |
|
9409 |
</function> |
|
9410 |
||
9411 |
<callback id="jvmtiExtensionEvent"> |
|
9412 |
<void/> |
|
9413 |
<synopsis>Extension Event</synopsis> |
|
9414 |
<description> |
|
9415 |
This is the implementation-specific event. |
|
9416 |
The event handler is set with |
|
9417 |
<functionlink id="SetExtensionEventCallback"/>. |
|
9418 |
<p/> |
|
9419 |
Event handlers for extension events must be declared varargs to match this definition. |
|
9420 |
Failure to do so could result in calling convention mismatch and undefined behavior |
|
9421 |
on some platforms. |
|
9422 |
<p/> |
|
9423 |
For example, if the <code>jvmtiParamInfo</code> |
|
9424 |
returned by <functionlink id="GetExtensionEvents"/> indicates that |
|
9425 |
there is a <code>jint</code> parameter, the event handler should be |
|
9426 |
declared: |
|
9427 |
<example> |
|
9428 |
void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...) |
|
9429 |
</example> |
|
9430 |
Note the terminal "<code>...</code>" which indicates varargs. |
|
9431 |
</description> |
|
9432 |
<parameters> |
|
9433 |
<param id="jvmti_env"> |
|
9434 |
<outptr> |
|
9435 |
<struct>jvmtiEnv</struct> |
|
9436 |
</outptr> |
|
9437 |
<description> |
|
9438 |
The <jvmti/> environment is the only fixed parameter for extension events. |
|
9439 |
</description> |
|
9440 |
</param> |
|
9441 |
<param id="..."> |
|
9442 |
<varargs/> |
|
9443 |
<description> |
|
9444 |
The extension event-specific parameters |
|
9445 |
</description> |
|
9446 |
</param> |
|
9447 |
</parameters> |
|
9448 |
</callback> |
|
9449 |
||
9450 |
<function id="SetExtensionEventCallback" phase="onload" num="126"> |
|
9451 |
<synopsis>Set Extension Event Callback</synopsis> |
|
9452 |
||
9453 |
<description> |
|
9454 |
Sets the callback function for an extension event and |
|
9455 |
enables the event. Or, if the callback is <code>NULL</code>, disables |
|
9456 |
the event. Note that unlike standard events, setting |
|
9457 |
the callback and enabling the event are a single operation. |
|
9458 |
</description> |
|
9459 |
<origin>new</origin> |
|
9460 |
<capabilities> |
|
9461 |
</capabilities> |
|
9462 |
<parameters> |
|
9463 |
<param id="extension_event_index"> |
|
9464 |
<jint/> |
|
9465 |
<description> |
|
9466 |
Identifies which callback to set. |
|
9467 |
This index is the |
|
9468 |
<fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink> |
|
9469 |
field of |
|
9470 |
<datalink id="jvmtiExtensionEventInfo"/>. |
|
9471 |
</description> |
|
9472 |
</param> |
|
9473 |
<param id="callback"> |
|
9474 |
<ptrtype> |
|
9475 |
<struct>jvmtiExtensionEvent</struct> |
|
9476 |
<nullok>disable the event</nullok> |
|
9477 |
</ptrtype> |
|
9478 |
<description> |
|
9479 |
If <code>callback</code> is non-<code>NULL</code>, |
|
9480 |
set <code>callback</code> to be the event callback function |
|
9481 |
and enable the event. |
|
9482 |
</description> |
|
9483 |
</param> |
|
9484 |
</parameters> |
|
9485 |
<errors> |
|
9486 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
9487 |
<paramlink id="extension_event_index"/> is not an |
|
9488 |
<fieldlink id="extension_event_index" |
|
9489 |
struct="jvmtiExtensionEventInfo"/> |
|
9490 |
returned by |
|
9491 |
<functionlink id="GetExtensionEvents"/> |
|
9492 |
</error> |
|
9493 |
</errors> |
|
9494 |
</function> |
|
9495 |
||
9496 |
</category> |
|
9497 |
||
9498 |
<category id="capability" label="Capability"> |
|
9499 |
||
9500 |
<intro> |
|
9501 |
The capabilities functions allow you to change the |
|
9502 |
functionality available to <jvmti/>--that is, |
|
9503 |
which <jvmti/> |
|
9504 |
functions can be called, what events can be generated, |
|
9505 |
and what functionality these events and functions can |
|
9506 |
provide. |
|
9507 |
<p/> |
|
9508 |
The "Capabilities" section of each function and event describe which |
|
9509 |
capabilities, if any, they are associated with. "Required Functionality" |
|
9510 |
means it is available for use and no capabilities must be added to use it. |
|
9511 |
"Optional Functionality" means the agent must possess the capability |
|
9512 |
before it can be used. |
|
9513 |
To possess a capability, the agent must |
|
9514 |
<functionlink id="AddCapabilities">add the capability</functionlink>. |
|
9515 |
"Optional Features" describe capabilities which, |
|
9516 |
if added, extend the feature set. |
|
9517 |
<p/> |
|
9518 |
The potentially available capabilities of each <jvmti/> implementation are different. |
|
9519 |
Depending on the implementation, a capability: |
|
9520 |
<ul> |
|
9521 |
<li>may never be added</li> |
|
9522 |
<li>may be added in either the <code>OnLoad</code> or live phase in any environment</li> |
|
9523 |
<li>may be added only during the <code>OnLoad</code> phase</li> |
|
9524 |
<li>may be possessed by only one environment at a time</li> |
|
9525 |
<li>may be possessed by only one environment at a time, |
|
9526 |
and only during the <code>OnLoad</code> phase</li> |
|
9527 |
<li>and so on ...</li> |
|
9528 |
</ul> |
|
9529 |
Frequently, the addition of a capability may incur a cost in execution speed, start up |
|
9530 |
time, and/or memory footprint. Note that the overhead of using a capability |
|
9531 |
is completely different than the overhead of possessing a capability. |
|
9532 |
Take single stepping as an example. When single stepping is on (that |
|
9533 |
is, when the event is enabled and thus actively sending events) |
|
9534 |
the overhead of sending and processing an event |
|
9535 |
on each instruction is huge in any implementation. |
|
9536 |
However, the overhead of possessing the capability may be small or large, |
|
9537 |
depending on the implementation. Also, when and if a capability is potentially |
|
9538 |
available depends on the implementation. Some examples: |
|
9539 |
<ul> |
|
9540 |
<li>One VM might perform all execution by compiling bytecodes into |
|
9541 |
native code and be unable to generate single step instructions. |
|
9542 |
In this implementation the capability can not be added.</li> |
|
9543 |
<li>Another VM may be able to switch execution to a single stepping |
|
9544 |
interpreter at any time. In this implementation, having the capability has no |
|
9545 |
overhead and could be added at any time.</li> |
|
9546 |
<li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted |
|
9547 |
execution engine at start up, but be unable to switch between them. |
|
9548 |
In this implementation the capability would need to be added |
|
9549 |
during the <code>OnLoad</code> phase (before bytecode |
|
9550 |
execution begins) and would have a large impact on execution speed |
|
9551 |
even if single stepping was never used.</li> |
|
9552 |
<li>Still another VM might be able to add an "is single stepping on" check |
|
9553 |
into compiled bytecodes or a generated interpreter. Again in this implementation |
|
9554 |
the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test |
|
9555 |
and branch on each instruction) would be considerably less.</li> |
|
9556 |
</ul> |
|
9557 |
<p/> |
|
9558 |
Each <jvmti/> <internallink id="environments">environment</internallink> |
|
9559 |
has its own set of capabilities. |
|
9560 |
Initially, that set is empty. |
|
9561 |
Any desired capability must be added. |
|
9562 |
If possible, capabilities should be added during the <code>OnLoad</code> phase. For most |
|
9563 |
virtual machines certain capabilities require special set up for |
|
9564 |
the virtual machine and this set up must happen |
|
9565 |
during the <code>OnLoad</code> phase, before the virtual machine begins execution. |
|
9566 |
Once a capability is added, it can |
|
9567 |
only be removed if explicitly relinquished by the environment. |
|
9568 |
<p/> |
|
9569 |
The agent can, |
|
9570 |
<functionlink id="GetPotentialCapabilities">determine what |
|
9571 |
capabilities this VM can potentially provide</functionlink>, |
|
9572 |
<functionlink id="AddCapabilities">add the capabilities |
|
9573 |
to be used</functionlink>, |
|
9574 |
<functionlink id="RelinquishCapabilities">release capabilities |
|
9575 |
which are no longer needed</functionlink>, and |
|
9576 |
<functionlink id="GetCapabilities">examine the currently available |
|
9577 |
capabilities</functionlink>. |
|
9578 |
</intro> |
|
9579 |
||
9580 |
<intro id="capabilityExamples" label="Capability Examples"> |
|
9581 |
For example, a freshly started agent (in the <code>OnLoad</code> function) |
|
9582 |
wants to enable all possible capabilities. |
|
9583 |
Note that, in general, this is not advisable as the agent may suffer |
|
9584 |
a performance penalty for functionality it is not using. |
|
9585 |
The code might look like this in C: |
|
9586 |
<example> |
|
9587 |
jvmtiCapabilities capa; |
|
9588 |
jvmtiError err; |
|
9589 |
||
9590 |
err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa); |
|
9591 |
if (err == JVMTI_ERROR_NONE) { |
|
9592 |
err = (*jvmti)->AddCapabilities(jvmti, &capa); |
|
9593 |
</example> |
|
9594 |
For example, if an agent wants to check if it can get |
|
9595 |
the bytecodes of a method (that is, it wants to check |
|
9596 |
if it previously added this capability and has not |
|
9597 |
relinquished it), the code might |
|
9598 |
look like this in C: |
|
9599 |
<example> |
|
9600 |
jvmtiCapabilities capa; |
|
9601 |
jvmtiError err; |
|
9602 |
||
9603 |
err = (*jvmti)->GetCapabilities(jvmti, &capa); |
|
9604 |
if (err == JVMTI_ERROR_NONE) { |
|
9605 |
if (capa.can_get_bytecodes) { ... } } |
|
9606 |
</example> |
|
9607 |
</intro> |
|
9608 |
||
9609 |
<capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure"> |
|
9610 |
<description> |
|
9611 |
The functions in this category use this capabilities structure |
|
9612 |
which contains boolean flags corresponding to each capability: |
|
9613 |
</description> |
|
9614 |
<capabilityfield id="can_tag_objects"> |
|
9615 |
<description> |
|
9616 |
Can set and get tags, as described in the |
|
9617 |
<internallink id="Heap">Heap category</internallink>. |
|
9618 |
</description> |
|
9619 |
</capabilityfield> |
|
9620 |
<capabilityfield id="can_generate_field_modification_events"> |
|
9621 |
<description> |
|
9622 |
Can set watchpoints on field modification - |
|
9623 |
<functionlink id="SetFieldModificationWatch"></functionlink> |
|
9624 |
</description> |
|
9625 |
</capabilityfield> |
|
9626 |
<capabilityfield id="can_generate_field_access_events"> |
|
9627 |
<description> |
|
9628 |
Can set watchpoints on field access - |
|
9629 |
<functionlink id="SetFieldAccessWatch"></functionlink> |
|
9630 |
</description> |
|
9631 |
</capabilityfield> |
|
9632 |
<capabilityfield id="can_get_bytecodes"> |
|
9633 |
<description> |
|
9634 |
Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink> |
|
9635 |
</description> |
|
9636 |
</capabilityfield> |
|
9637 |
<capabilityfield id="can_get_synthetic_attribute"> |
|
9638 |
<description> |
|
9639 |
Can test if a field or method is synthetic - |
|
9640 |
<functionlink id="IsFieldSynthetic"></functionlink> and |
|
9641 |
<functionlink id="IsMethodSynthetic"></functionlink> |
|
9642 |
</description> |
|
9643 |
</capabilityfield> |
|
9644 |
<capabilityfield id="can_get_owned_monitor_info"> |
|
9645 |
<description> |
|
9646 |
Can get information about ownership of monitors - |
|
9647 |
<functionlink id="GetOwnedMonitorInfo"></functionlink> |
|
9648 |
</description> |
|
9649 |
</capabilityfield> |
|
9650 |
<capabilityfield id="can_get_current_contended_monitor"> |
|
9651 |
<description> |
|
9652 |
Can <functionlink id="GetCurrentContendedMonitor"></functionlink> |
|
9653 |
</description> |
|
9654 |
</capabilityfield> |
|
9655 |
<capabilityfield id="can_get_monitor_info"> |
|
9656 |
<description> |
|
9657 |
Can <functionlink id="GetObjectMonitorUsage"></functionlink> |
|
9658 |
</description> |
|
9659 |
</capabilityfield> |
|
9660 |
<capabilityfield id="can_pop_frame"> |
|
9661 |
<description> |
|
9662 |
Can pop frames off the stack - <functionlink id="PopFrame"></functionlink> |
|
9663 |
</description> |
|
9664 |
</capabilityfield> |
|
9665 |
<capabilityfield id="can_redefine_classes"> |
|
9666 |
<description> |
|
9667 |
Can redefine classes with <functionlink id="RedefineClasses"/>. |
|
9668 |
</description> |
|
9669 |
</capabilityfield> |
|
9670 |
<capabilityfield id="can_signal_thread"> |
|
9671 |
<description> |
|
9672 |
Can send stop or interrupt to threads |
|
9673 |
</description> |
|
9674 |
</capabilityfield> |
|
9675 |
<capabilityfield id="can_get_source_file_name"> |
|
9676 |
<description> |
|
9677 |
Can get the source file name of a class |
|
9678 |
</description> |
|
9679 |
</capabilityfield> |
|
9680 |
<capabilityfield id="can_get_line_numbers"> |
|
9681 |
<description> |
|
9682 |
Can get the line number table of a method |
|
9683 |
</description> |
|
9684 |
</capabilityfield> |
|
9685 |
<capabilityfield id="can_get_source_debug_extension"> |
|
9686 |
<description> |
|
9687 |
Can get the source debug extension of a class |
|
9688 |
</description> |
|
9689 |
</capabilityfield> |
|
9690 |
<capabilityfield id="can_access_local_variables"> |
|
9691 |
<description> |
|
9692 |
Can set and get local variables |
|
9693 |
</description> |
|
9694 |
</capabilityfield> |
|
9695 |
<capabilityfield id="can_maintain_original_method_order"> |
|
9696 |
<description> |
|
9697 |
Can return methods in the order they occur in the class file |
|
9698 |
</description> |
|
9699 |
</capabilityfield> |
|
9700 |
<capabilityfield id="can_generate_single_step_events"> |
|
9701 |
<description> |
|
9702 |
Can get <eventlink id="SingleStep">single step</eventlink> events |
|
9703 |
</description> |
|
9704 |
</capabilityfield> |
|
9705 |
<capabilityfield id="can_generate_exception_events"> |
|
9706 |
<description> |
|
9707 |
Can get <eventlink id="Exception">exception thrown</eventlink> and |
|
9708 |
<eventlink id="ExceptionCatch">exception catch</eventlink> events |
|
9709 |
</description> |
|
9710 |
</capabilityfield> |
|
9711 |
<capabilityfield id="can_generate_frame_pop_events"> |
|
9712 |
<description> |
|
9713 |
Can <functionlink id="NotifyFramePop">set</functionlink> and thus get |
|
9714 |
<eventlink id="FramePop"></eventlink> events |
|
9715 |
</description> |
|
9716 |
</capabilityfield> |
|
9717 |
<capabilityfield id="can_generate_breakpoint_events"> |
|
9718 |
<description> |
|
9719 |
Can <functionlink id="SetBreakpoint">set</functionlink> and thus get |
|
9720 |
<eventlink id="Breakpoint"></eventlink> events |
|
9721 |
</description> |
|
9722 |
</capabilityfield> |
|
9723 |
<capabilityfield id="can_suspend"> |
|
9724 |
<description> |
|
9725 |
Can suspend and resume threads |
|
9726 |
</description> |
|
9727 |
</capabilityfield> |
|
9728 |
<capabilityfield id="can_redefine_any_class"> |
|
9729 |
<description> |
|
9730 |
Can modify (retransform or redefine) any non-primitive non-array class. |
|
9731 |
See <functionlink id="IsModifiableClass"/>. |
|
9732 |
</description> |
|
9733 |
</capabilityfield> |
|
9734 |
<capabilityfield id="can_get_current_thread_cpu_time"> |
|
9735 |
<description> |
|
9736 |
Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink> |
|
9737 |
current thread CPU time |
|
9738 |
</description> |
|
9739 |
</capabilityfield> |
|
9740 |
<capabilityfield id="can_get_thread_cpu_time"> |
|
9741 |
<description> |
|
9742 |
Can <functionlink id="GetThreadCpuTime">get</functionlink> |
|
9743 |
thread CPU time |
|
9744 |
</description> |
|
9745 |
</capabilityfield> |
|
9746 |
<capabilityfield id="can_generate_method_entry_events" |
|
9747 |
disp1="can_generate" disp2="_method_entry_events" |
|
9748 |
> |
|
9749 |
<description> |
|
9750 |
Can generate method entry events on entering a method |
|
9751 |
</description> |
|
9752 |
</capabilityfield> |
|
9753 |
<capabilityfield id="can_generate_method_exit_events" |
|
9754 |
disp1="can_generate" disp2="_method_exit_events" |
|
9755 |
> |
|
9756 |
<description> |
|
9757 |
Can generate method exit events on leaving a method |
|
9758 |
</description> |
|
9759 |
</capabilityfield> |
|
9760 |
<capabilityfield id="can_generate_all_class_hook_events" |
|
9761 |
disp1="can_generate" disp2="_all_class_hook_events" |
|
9762 |
> |
|
9763 |
<description> |
|
9764 |
Can generate ClassFileLoadHook events for every loaded class. |
|
9765 |
</description> |
|
9766 |
</capabilityfield> |
|
9767 |
<capabilityfield id="can_generate_compiled_method_load_events" |
|
9768 |
disp1="can_generate" disp2="_compiled_method_load_events" |
|
9769 |
> |
|
9770 |
<description> |
|
9771 |
Can generate events when a method is compiled or unloaded |
|
9772 |
</description> |
|
9773 |
</capabilityfield> |
|
9774 |
<capabilityfield id="can_generate_monitor_events" |
|
9775 |
disp1="can_generate" disp2="_monitor_events" |
|
9776 |
> |
|
9777 |
<description> |
|
9778 |
Can generate events on monitor activity |
|
9779 |
</description> |
|
9780 |
</capabilityfield> |
|
9781 |
<capabilityfield id="can_generate_vm_object_alloc_events" |
|
9782 |
disp1="can_generate" disp2="_vm_object_alloc_events" |
|
9783 |
> |
|
9784 |
<description> |
|
9785 |
Can generate events on VM allocation of an object |
|
9786 |
</description> |
|
9787 |
</capabilityfield> |
|
9788 |
<capabilityfield id="can_generate_native_method_bind_events" |
|
9789 |
disp1="can_generate" disp2="_native_method_bind_events" |
|
9790 |
> |
|
9791 |
<description> |
|
9792 |
Can generate events when a native method is bound to its |
|
9793 |
implementation |
|
9794 |
</description> |
|
9795 |
</capabilityfield> |
|
9796 |
<capabilityfield id="can_generate_garbage_collection_events" |
|
9797 |
disp1="can_generate" disp2="_garbage_collection_events" |
|
9798 |
> |
|
9799 |
<description> |
|
9800 |
Can generate events when garbage collection begins or ends |
|
9801 |
</description> |
|
9802 |
</capabilityfield> |
|
9803 |
<capabilityfield id="can_generate_object_free_events" |
|
9804 |
disp1="can_generate" disp2="_object_free_events" |
|
9805 |
> |
|
9806 |
<description> |
|
9807 |
Can generate events when the garbage collector frees an object |
|
9808 |
</description> |
|
9809 |
</capabilityfield> |
|
9810 |
<capabilityfield id="can_force_early_return" since="1.1"> |
|
9811 |
<description> |
|
9812 |
Can return early from a method, as described in the |
|
9813 |
<internallink id="ForceEarlyReturn">Force Early Return category</internallink>. |
|
9814 |
</description> |
|
9815 |
</capabilityfield> |
|
9816 |
<capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1"> |
|
9817 |
<description> |
|
9818 |
Can get information about owned monitors with stack depth - |
|
9819 |
<functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink> |
|
9820 |
</description> |
|
9821 |
</capabilityfield> |
|
9822 |
<capabilityfield id="can_get_constant_pool" since="1.1"> |
|
9823 |
<description> |
|
9824 |
Can get the constant pool of a class - |
|
9825 |
<functionlink id="GetConstantPool"></functionlink> |
|
9826 |
</description> |
|
9827 |
</capabilityfield> |
|
9828 |
<capabilityfield id="can_set_native_method_prefix" since="1.1"> |
|
9829 |
<description> |
|
9830 |
Can set prefix to be applied when native method cannot be resolved - |
|
9831 |
<functionlink id="SetNativeMethodPrefix"/> and |
|
9832 |
<functionlink id="SetNativeMethodPrefixes"/> |
|
9833 |
</description> |
|
9834 |
</capabilityfield> |
|
9835 |
<capabilityfield id="can_retransform_classes" since="1.1"> |
|
9836 |
<description> |
|
9837 |
Can retransform classes with <functionlink id="RetransformClasses"/>. |
|
9838 |
In addition to the restrictions imposed by the specific |
|
9839 |
implementation on this capability (see the |
|
9840 |
<internallink id="capability">Capability</internallink> section), |
|
9841 |
this capability must be set before the |
|
9842 |
<eventlink id="ClassFileLoadHook"/> event is enabled for the |
|
9843 |
first time in this environment. |
|
9844 |
An environment that possesses this capability at the time that |
|
9845 |
<code>ClassFileLoadHook</code> is enabled for the first time is |
|
9846 |
said to be <i>retransformation capable</i>. |
|
9847 |
An environment that does not possess this capability at the time that |
|
9848 |
<code>ClassFileLoadHook</code> is enabled for the first time is |
|
9849 |
said to be <i>retransformation incapable</i>. |
|
9850 |
</description> |
|
9851 |
</capabilityfield> |
|
9852 |
<capabilityfield id="can_retransform_any_class" since="1.1"> |
|
9853 |
<description> |
|
9854 |
<functionlink id="RetransformClasses"/> can be called on any class |
|
9855 |
(<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/> |
|
9856 |
must also be set) |
|
9857 |
</description> |
|
9858 |
</capabilityfield> |
|
9859 |
<capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1"> |
|
9860 |
<description> |
|
9861 |
Can generate events when the VM is unable to allocate memory from |
|
9862 |
the <tm>Java</tm> platform heap. |
|
9863 |
See <eventlink id="ResourceExhausted"/>. |
|
9864 |
</description> |
|
9865 |
</capabilityfield> |
|
9866 |
<capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1"> |
|
9867 |
<description> |
|
9868 |
Can generate events when the VM is unable to create a thread. |
|
9869 |
See <eventlink id="ResourceExhausted"/>. |
|
9870 |
</description> |
|
9871 |
</capabilityfield> |
|
9872 |
</capabilitiestypedef> |
|
9873 |
||
9874 |
<function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> |
|
9875 |
<synopsis>Get Potential Capabilities</synopsis> |
|
9876 |
<description> |
|
9877 |
Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> |
|
9878 |
features that can potentially be possessed by this environment |
|
9879 |
at this time. |
|
9880 |
The returned capabilities differ from the complete set of capabilities |
|
9881 |
implemented by the VM in two cases: another environment possesses |
|
9882 |
capabilities that can only be possessed by one environment, or the |
|
9883 |
current <functionlink id="GetPhase">phase</functionlink> is live, |
|
9884 |
and certain capabilities can only be added during the <code>OnLoad</code> phase. |
|
9885 |
The <functionlink id="AddCapabilities"></functionlink> function |
|
9886 |
may be used to set any or all or these capabilities. |
|
9887 |
Currently possessed capabilities are included. |
|
9888 |
<p/> |
|
9889 |
Typically this function is used in the <code>OnLoad</code> function. |
|
9890 |
Some virtual machines may allow a limited set of capabilities to be |
|
9891 |
added in the live phase. |
|
9892 |
In this case, the set of potentially available capabilities |
|
9893 |
will likely differ from the <code>OnLoad</code> phase set. |
|
9894 |
<p/> |
|
9895 |
See the |
|
9896 |
<internallink id="capabilityExamples">Capability Examples</internallink>. |
|
9897 |
</description> |
|
9898 |
<origin>new</origin> |
|
9899 |
<capabilities> |
|
9900 |
</capabilities> |
|
9901 |
<parameters> |
|
9902 |
<param id="capabilities_ptr"> |
|
9903 |
<outptr><struct>jvmtiCapabilities</struct></outptr> |
|
9904 |
<description> |
|
9905 |
On return, points to the <jvmti/> capabilities that may be added. |
|
9906 |
</description> |
|
9907 |
</param> |
|
9908 |
</parameters> |
|
9909 |
<errors> |
|
9910 |
</errors> |
|
9911 |
</function> |
|
9912 |
||
9913 |
<elide> |
|
9914 |
<function id="EstimateCostOfCapabilities" phase="onload" num="141"> |
|
9915 |
<synopsis>Estimate Cost Of Capabilities</synopsis> |
|
9916 |
<description> |
|
9917 |
<issue>There is strong opposition to this function. The concern is |
|
9918 |
that it would be difficult or impossible to provide meaningful |
|
9919 |
numbers, as the amount of impact is conditional on many factors |
|
9920 |
that a single number could not represent. There is doubt that |
|
9921 |
conditional implementations would be used or are even a good idea. |
|
9922 |
The thought is that release documentation for the implementation |
|
9923 |
would be the best means of exposing this information. |
|
9924 |
Unless new arguments are presented, I intend to remove this |
|
9925 |
function in the next revision. |
|
9926 |
</issue> |
|
9927 |
<p/> |
|
9928 |
Return via the <paramlink id="time_impact_ptr"></paramlink> and |
|
9929 |
<paramlink id="space_impact_ptr"></paramlink> an estimate of the impact |
|
9930 |
of adding the capabilities pointed to by |
|
9931 |
<paramlink id="capabilities_ptr"></paramlink>. |
|
9932 |
The returned estimates are in percentage of additional overhead, thus |
|
9933 |
a time impact of 100 mean the application might run |
|
9934 |
at half the speed. |
|
9935 |
The estimates are very rough approximations and are not guaranteed. |
|
9936 |
Note also, that the estimates are of the impact of having the |
|
9937 |
capability available--when and if it is used the impact may be |
|
9938 |
much greater. |
|
9939 |
Estimates can be for a single capability or for a set of |
|
9940 |
capabilities. Note that the costs are not necessarily additive, |
|
9941 |
adding support for one capability might make another available |
|
9942 |
for free or conversely having two capabilities at once may |
|
9943 |
have multiplicative impact. |
|
9944 |
Estimates are relative to the current set of capabilities - |
|
9945 |
that is, how much more impact given the currently possessed capabilities. |
|
9946 |
<p/> |
|
9947 |
Typically this function is used in the OnLoad function, |
|
9948 |
some virtual machines may allow a limited set of capabilities to be |
|
9949 |
added in the live phase. |
|
9950 |
In this case, the set of potentially available capabilities |
|
9951 |
will likely differ from the OnLoad phase set. |
|
9952 |
<p/> |
|
9953 |
See the |
|
9954 |
<internallink id="capabilityExamples">Capability Examples</internallink>. |
|
9955 |
</description> |
|
9956 |
<origin>new</origin> |
|
9957 |
<capabilities> |
|
9958 |
</capabilities> |
|
9959 |
<parameters> |
|
9960 |
<param id="capabilities_ptr"> |
|
9961 |
<inptr><struct>jvmtiCapabilities</struct></inptr> |
|
9962 |
<description> |
|
9963 |
points to the <jvmti/> capabilities to evaluate. |
|
9964 |
</description> |
|
9965 |
</param> |
|
9966 |
<param id="time_impact_ptr"> |
|
9967 |
<outptr><jint/></outptr> |
|
9968 |
<description> |
|
9969 |
On return, points to the estimated percentage increase in |
|
9970 |
run time if this capability was added. |
|
9971 |
</description> |
|
9972 |
</param> |
|
9973 |
<param id="space_impact_ptr"> |
|
9974 |
<outptr><jint/></outptr> |
|
9975 |
<description> |
|
9976 |
On return, points to the estimated percentage increase in |
|
9977 |
memory space used if this capability was added. |
|
9978 |
</description> |
|
9979 |
</param> |
|
9980 |
</parameters> |
|
9981 |
<errors> |
|
9982 |
<error id="JVMTI_ERROR_NOT_AVAILABLE"> |
|
9983 |
The desired capabilities are not even potentially available. |
|
9984 |
</error> |
|
9985 |
</errors> |
|
9986 |
</function> |
|
9987 |
</elide> |
|
9988 |
||
9989 |
<function id="AddCapabilities" jkernel="yes" phase="onload" num="142"> |
|
9990 |
<synopsis>Add Capabilities</synopsis> |
|
9991 |
<description> |
|
9992 |
Set new capabilities by adding the capabilities |
|
9993 |
whose values are set to one (<code>1</code>) in |
|
9994 |
<code>*</code><paramlink id="capabilities_ptr"></paramlink>. |
|
9995 |
All previous capabilities are retained. |
|
9996 |
Typically this function is used in the <code>OnLoad</code> function. |
|
9997 |
Some virtual machines may allow a limited set of capabilities to be |
|
9998 |
added in the live phase. |
|
9999 |
<p/> |
|
10000 |
See the |
|
10001 |
<internallink id="capabilityExamples">Capability Examples</internallink>. |
|
10002 |
</description> |
|
10003 |
<origin>new</origin> |
|
10004 |
<capabilities> |
|
10005 |
</capabilities> |
|
10006 |
<parameters> |
|
10007 |
<param id="capabilities_ptr"> |
|
10008 |
<inptr><struct>jvmtiCapabilities</struct></inptr> |
|
10009 |
<description> |
|
10010 |
Points to the <jvmti/> capabilities to add. |
|
10011 |
</description> |
|
10012 |
</param> |
|
10013 |
</parameters> |
|
10014 |
<errors> |
|
10015 |
<error id="JVMTI_ERROR_NOT_AVAILABLE"> |
|
10016 |
The desired capabilities are not even potentially available. |
|
10017 |
</error> |
|
10018 |
</errors> |
|
10019 |
</function> |
|
10020 |
||
10021 |
||
10022 |
<function id="RelinquishCapabilities" phase="onload" num="143"> |
|
10023 |
<synopsis>Relinquish Capabilities</synopsis> |
|
10024 |
<description> |
|
10025 |
Relinquish the capabilities |
|
10026 |
whose values are set to one (<code>1</code>) in |
|
10027 |
<code>*</code><paramlink id="capabilities_ptr"></paramlink>. |
|
10028 |
Some implementations may allow only one environment to have a capability |
|
10029 |
(see the <internallink id="capability">capability introduction</internallink>). |
|
10030 |
This function releases capabilities |
|
10031 |
so that they may be used by other agents. |
|
10032 |
All other capabilities are retained. |
|
10033 |
The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>. |
|
10034 |
Attempting to relinquish a capability that the agent does not possess is not an error. |
|
10035 |
<issue> |
|
10036 |
It is possible for the agent to be actively using capabilities |
|
10037 |
which are being relinquished. For example, a thread is currently |
|
10038 |
suspended and can_suspend is being relinquished or an event is currently |
|
10039 |
enabled and can_generate_whatever is being relinquished. |
|
10040 |
There are three possible ways we could spec this: |
|
10041 |
<ul> |
|
10042 |
<li>relinquish automatically releases them</li> |
|
10043 |
<li>relinquish checks and returns some error code if held</li> |
|
10044 |
<li>it is the agent's responsibility and it is not checked</li> |
|
10045 |
</ul> |
|
10046 |
One of these should be chosen. |
|
10047 |
</issue> |
|
10048 |
</description> |
|
10049 |
<origin>new</origin> |
|
10050 |
<capabilities> |
|
10051 |
</capabilities> |
|
10052 |
<parameters> |
|
10053 |
<param id="capabilities_ptr"> |
|
10054 |
<inptr><struct>jvmtiCapabilities</struct></inptr> |
|
10055 |
<description> |
|
10056 |
Points to the <jvmti/> capabilities to relinquish. |
|
10057 |
</description> |
|
10058 |
</param> |
|
10059 |
</parameters> |
|
10060 |
<errors> |
|
10061 |
</errors> |
|
10062 |
</function> |
|
10063 |
||
10064 |
||
10065 |
||
10066 |
<function id="GetCapabilities" jkernel="yes" phase="any" num="89"> |
|
10067 |
<synopsis>Get Capabilities</synopsis> |
|
10068 |
<description> |
|
10069 |
Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> |
|
10070 |
features which this environment currently possesses. |
|
10071 |
Each possessed capability is indicated by a one (<code>1</code>) in the |
|
10072 |
corresponding field of the <internallink id="jvmtiCapabilities">capabilities |
|
10073 |
structure</internallink>. |
|
10074 |
An environment does not possess a capability unless it has been successfully added with |
|
10075 |
<functionlink id="AddCapabilities"/>. |
|
10076 |
An environment only loses possession of a capability if it has been relinquished with |
|
10077 |
<functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result |
|
10078 |
of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which |
|
10079 |
have been made. |
|
10080 |
<p/> |
|
10081 |
See the |
|
10082 |
<internallink id="capabilityExamples">Capability Examples</internallink>. |
|
10083 |
</description> |
|
10084 |
<origin>jvmdiClone</origin> |
|
10085 |
<capabilities> |
|
10086 |
</capabilities> |
|
10087 |
<parameters> |
|
10088 |
<param id="capabilities_ptr"> |
|
10089 |
<outptr><struct>jvmtiCapabilities</struct></outptr> |
|
10090 |
<description> |
|
10091 |
On return, points to the <jvmti/> capabilities. |
|
10092 |
</description> |
|
10093 |
</param> |
|
10094 |
</parameters> |
|
10095 |
<errors> |
|
10096 |
</errors> |
|
10097 |
</function> |
|
10098 |
||
10099 |
</category> |
|
10100 |
||
10101 |
||
10102 |
<category id="timers" label="Timers"> |
|
10103 |
||
10104 |
<intro> |
|
10105 |
These functions provide timing information. |
|
10106 |
The resolution at which the time is updated is not specified. |
|
10107 |
They provides nanosecond precision, but not necessarily nanosecond accuracy. |
|
10108 |
Details about the timers, such as their maximum values, can be accessed with |
|
10109 |
the timer information functions. |
|
10110 |
</intro> |
|
10111 |
||
10112 |
<typedef id="jvmtiTimerInfo" label="Timer Info"> |
|
10113 |
<description> |
|
10114 |
The information function for each timer returns this data structure. |
|
10115 |
</description> |
|
10116 |
<field id="max_value"> |
|
10117 |
<jlong/> |
|
10118 |
<description> |
|
10119 |
The maximum value the timer can reach. |
|
10120 |
After this value is reached the timer wraps back to zero. |
|
10121 |
This is an unsigned value. If tested or printed as a jlong (signed value) |
|
10122 |
it may appear to be a negative number. |
|
10123 |
</description> |
|
10124 |
</field> |
|
10125 |
<field id="may_skip_forward"> |
|
10126 |
<jboolean/> |
|
10127 |
<description> |
|
10128 |
If true, the timer can be externally adjusted and as a result skip forward. |
|
10129 |
If false, the timer value will never increase faster than real time. |
|
10130 |
</description> |
|
10131 |
</field> |
|
10132 |
<field id="may_skip_backward"> |
|
10133 |
<jboolean/> |
|
10134 |
<description> |
|
10135 |
If true, the timer can be externally adjusted and as a result skip backward. |
|
10136 |
If false, the timer value will be monotonically increasing. |
|
10137 |
</description> |
|
10138 |
</field> |
|
10139 |
<field id="kind"> |
|
10140 |
<enum>jvmtiTimerKind</enum> |
|
10141 |
<description> |
|
10142 |
The kind of timer. |
|
10143 |
On a platform that does not distinguish between user and system time, <datalink |
|
10144 |
id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink> |
|
10145 |
is returned. |
|
10146 |
</description> |
|
10147 |
</field> |
|
10148 |
<field id="reserved1"> |
|
10149 |
<jlong/> |
|
10150 |
<description> |
|
10151 |
Reserved for future use. |
|
10152 |
</description> |
|
10153 |
</field> |
|
10154 |
<field id="reserved2"> |
|
10155 |
<jlong/> |
|
10156 |
<description> |
|
10157 |
Reserved for future use. |
|
10158 |
</description> |
|
10159 |
</field> |
|
10160 |
</typedef> |
|
10161 |
||
10162 |
<intro> |
|
10163 |
Where the timer kind is -- |
|
10164 |
||
10165 |
<constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum"> |
|
10166 |
<constant id="JVMTI_TIMER_USER_CPU" num="30"> |
|
10167 |
CPU time that a thread is in user mode. |
|
10168 |
</constant> |
|
10169 |
<constant id="JVMTI_TIMER_TOTAL_CPU" num="31"> |
|
10170 |
CPU time that a thread is in user or system mode. |
|
10171 |
</constant> |
|
10172 |
<constant id="JVMTI_TIMER_ELAPSED" num="32"> |
|
10173 |
Elapsed time. |
|
10174 |
</constant> |
|
10175 |
</constants> |
|
10176 |
</intro> |
|
10177 |
||
10178 |
<function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134"> |
|
10179 |
<synopsis>Get Current Thread CPU Timer Information</synopsis> |
|
10180 |
<description> |
|
10181 |
Get information about the |
|
10182 |
<functionlink id="GetCurrentThreadCpuTime"/> timer. |
|
10183 |
The fields of the <datalink id="jvmtiTimerInfo"/> structure |
|
10184 |
are filled in with details about the timer. |
|
10185 |
This information is specific to the platform and the implementation of |
|
10186 |
<functionlink id="GetCurrentThreadCpuTime"/> and thus |
|
10187 |
does not vary by thread nor does it vary |
|
10188 |
during a particular invocation of the VM. |
|
10189 |
<p/> |
|
10190 |
Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> |
|
10191 |
and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values |
|
10192 |
returned by <code>GetCurrentThreadCpuTimerInfo</code> |
|
10193 |
and <functionlink id="GetThreadCpuTimerInfo"/> |
|
10194 |
may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. |
|
10195 |
</description> |
|
10196 |
<origin>new</origin> |
|
10197 |
<capabilities> |
|
10198 |
<required id="can_get_current_thread_cpu_time"> |
|
10199 |
Can get current thread CPU time. |
|
10200 |
</required> |
|
10201 |
</capabilities> |
|
10202 |
<parameters> |
|
10203 |
<param id="info_ptr"> |
|
10204 |
<outptr><struct>jvmtiTimerInfo</struct></outptr> |
|
10205 |
<description> |
|
10206 |
On return, filled with information describing the time |
|
10207 |
returned by <functionlink id="GetCurrentThreadCpuTime"/>. |
|
10208 |
</description> |
|
10209 |
</param> |
|
10210 |
</parameters> |
|
10211 |
<errors> |
|
10212 |
</errors> |
|
10213 |
</function> |
|
10214 |
||
10215 |
<function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135"> |
|
10216 |
<synopsis>Get Current Thread CPU Time</synopsis> |
|
10217 |
<description> |
|
10218 |
Return the CPU time utilized by the current thread. |
|
10219 |
<p/> |
|
10220 |
Note that the <functionlink id="GetThreadCpuTime"/> |
|
10221 |
function provides CPU time for any thread, including |
|
10222 |
the current thread. <code>GetCurrentThreadCpuTime</code> |
|
10223 |
exists to support platforms which cannot |
|
10224 |
supply CPU time for threads other than the current |
|
10225 |
thread or which have more accurate information for |
|
10226 |
the current thread (see |
|
10227 |
<functionlink id="GetCurrentThreadCpuTimerInfo"/> vs |
|
10228 |
<functionlink id="GetThreadCpuTimerInfo"/>). |
|
10229 |
On many platforms this call will be equivalent to: |
|
10230 |
<example> |
|
10231 |
GetThreadCpuTime(env, NULL, nanos_ptr) |
|
10232 |
</example> |
|
10233 |
</description> |
|
10234 |
<origin>new</origin> |
|
10235 |
<capabilities> |
|
10236 |
<required id="can_get_current_thread_cpu_time"> |
|
10237 |
Can get current thread CPU time. |
|
10238 |
<p/> |
|
10239 |
If this capability is enabled after threads have started, |
|
10240 |
the implementation may choose any time up |
|
10241 |
to and including the time that the capability is enabled |
|
10242 |
as the point where CPU time collection starts. |
|
10243 |
<p/> |
|
10244 |
This capability must be potentially available on any |
|
10245 |
platform where |
|
10246 |
<internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink> |
|
10247 |
is potentially available. |
|
10248 |
</required> |
|
10249 |
</capabilities> |
|
10250 |
<parameters> |
|
10251 |
<param id="nanos_ptr"> |
|
10252 |
<outptr><jlong/></outptr> |
|
10253 |
<description> |
|
10254 |
On return, points to the CPU time used by this thread |
|
10255 |
in nanoseconds. |
|
10256 |
This is an unsigned value. If tested or printed as a jlong (signed value) |
|
10257 |
it may appear to be a negative number. |
|
10258 |
</description> |
|
10259 |
</param> |
|
10260 |
</parameters> |
|
10261 |
<errors> |
|
10262 |
</errors> |
|
10263 |
</function> |
|
10264 |
||
10265 |
<function id="GetThreadCpuTimerInfo" num="136"> |
|
10266 |
<synopsis>Get Thread CPU Timer Information</synopsis> |
|
10267 |
<description> |
|
10268 |
Get information about the |
|
10269 |
<functionlink id="GetThreadCpuTime"/> timer. |
|
10270 |
The fields of the <datalink id="jvmtiTimerInfo"/> structure |
|
10271 |
are filled in with details about the timer. |
|
10272 |
This information is specific to the platform and the implementation of |
|
10273 |
<functionlink id="GetThreadCpuTime"/> and thus |
|
10274 |
does not vary by thread nor does it vary |
|
10275 |
during a particular invocation of the VM. |
|
10276 |
<p/> |
|
10277 |
Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/> |
|
10278 |
and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values |
|
10279 |
returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/> |
|
10280 |
and <code>GetThreadCpuTimerInfo</code> |
|
10281 |
may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information. |
|
10282 |
</description> |
|
10283 |
<origin>new</origin> |
|
10284 |
<capabilities> |
|
10285 |
<required id="can_get_thread_cpu_time"> |
|
10286 |
Can get thread CPU time. |
|
10287 |
</required> |
|
10288 |
</capabilities> |
|
10289 |
<parameters> |
|
10290 |
<param id="info_ptr"> |
|
10291 |
<outptr><struct>jvmtiTimerInfo</struct></outptr> |
|
10292 |
<description> |
|
10293 |
On return, filled with information describing the time |
|
10294 |
returned by <functionlink id="GetThreadCpuTime"/>. |
|
10295 |
</description> |
|
10296 |
</param> |
|
10297 |
</parameters> |
|
10298 |
<errors> |
|
10299 |
</errors> |
|
10300 |
</function> |
|
10301 |
||
10302 |
<function id="GetThreadCpuTime" num="137"> |
|
10303 |
<synopsis>Get Thread CPU Time</synopsis> |
|
10304 |
<description> |
|
10305 |
Return the CPU time utilized by the specified thread. |
|
10306 |
<p/> |
|
10307 |
Get information about this timer with |
|
10308 |
<functionlink id="GetThreadCpuTimerInfo"/>. |
|
10309 |
</description> |
|
10310 |
<origin>new</origin> |
|
10311 |
<capabilities> |
|
10312 |
<required id="can_get_thread_cpu_time"> |
|
10313 |
Can get thread CPU time. |
|
10314 |
<p/> |
|
10315 |
If this capability is enabled after threads have started, |
|
10316 |
the implementation may choose any time up |
|
10317 |
to and including the time that the capability is enabled |
|
10318 |
as the point where CPU time collection starts. |
|
10319 |
</required> |
|
10320 |
</capabilities> |
|
10321 |
<parameters> |
|
10322 |
<param id="thread"> |
|
10323 |
<jthread null="current"/> |
|
10324 |
<description> |
|
10325 |
The thread to query. |
|
10326 |
</description> |
|
10327 |
</param> |
|
10328 |
<param id="nanos_ptr"> |
|
10329 |
<outptr><jlong/></outptr> |
|
10330 |
<description> |
|
10331 |
On return, points to the CPU time used by the specified thread |
|
10332 |
in nanoseconds. |
|
10333 |
This is an unsigned value. If tested or printed as a jlong (signed value) |
|
10334 |
it may appear to be a negative number. |
|
10335 |
</description> |
|
10336 |
</param> |
|
10337 |
</parameters> |
|
10338 |
<errors> |
|
10339 |
</errors> |
|
10340 |
</function> |
|
10341 |
||
10342 |
<function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138"> |
|
10343 |
<synopsis>Get Timer Information</synopsis> |
|
10344 |
<description> |
|
10345 |
Get information about the |
|
10346 |
<functionlink id="GetTime"/> timer. |
|
10347 |
The fields of the <datalink id="jvmtiTimerInfo"/> structure |
|
10348 |
are filled in with details about the timer. |
|
10349 |
This information will not change during a particular invocation of the VM. |
|
10350 |
</description> |
|
10351 |
<origin>new</origin> |
|
10352 |
<capabilities> |
|
10353 |
</capabilities> |
|
10354 |
<parameters> |
|
10355 |
<param id="info_ptr"> |
|
10356 |
<outptr><struct>jvmtiTimerInfo</struct></outptr> |
|
10357 |
<description> |
|
10358 |
On return, filled with information describing the time |
|
10359 |
returned by <functionlink id="GetTime"/>. |
|
10360 |
</description> |
|
10361 |
</param> |
|
10362 |
</parameters> |
|
10363 |
<errors> |
|
10364 |
</errors> |
|
10365 |
</function> |
|
10366 |
||
10367 |
<function id="GetTime" phase="any" callbacksafe="safe" num="139"> |
|
10368 |
<synopsis>Get Time</synopsis> |
|
10369 |
<description> |
|
10370 |
Return the current value of the system timer, in nanoseconds. |
|
10371 |
<p/> |
|
10372 |
The value returned represents nanoseconds since some fixed but |
|
10373 |
arbitrary time (perhaps in the future, so values may be |
|
10374 |
negative). This function provides nanosecond precision, but not |
|
10375 |
necessarily nanosecond accuracy. No guarantees are made about |
|
10376 |
how frequently values change. |
|
10377 |
<p/> |
|
10378 |
Get information about this timer with |
|
10379 |
<functionlink id="GetTimerInfo"/>. |
|
10380 |
</description> |
|
10381 |
<origin>new</origin> |
|
10382 |
<capabilities> |
|
10383 |
</capabilities> |
|
10384 |
<parameters> |
|
10385 |
<param id="nanos_ptr"> |
|
10386 |
<outptr><jlong/></outptr> |
|
10387 |
<description> |
|
10388 |
On return, points to the time in nanoseconds. |
|
10389 |
This is an unsigned value. If tested or printed as a jlong (signed value) |
|
10390 |
it may appear to be a negative number. |
|
10391 |
</description> |
|
10392 |
</param> |
|
10393 |
</parameters> |
|
10394 |
<errors> |
|
10395 |
</errors> |
|
10396 |
</function> |
|
10397 |
||
10398 |
<function id="GetAvailableProcessors" phase="any" num="144"> |
|
10399 |
<synopsis>Get Available Processors</synopsis> |
|
10400 |
<description> |
|
10401 |
Returns the number of processors available to the Java virtual machine. |
|
10402 |
<p/> |
|
10403 |
This value may change during a particular invocation of the virtual machine. |
|
10404 |
Applications that are sensitive to the number of available processors should |
|
10405 |
therefore occasionally poll this property. |
|
10406 |
</description> |
|
10407 |
<origin>new</origin> |
|
10408 |
<capabilities> |
|
10409 |
</capabilities> |
|
10410 |
<parameters> |
|
10411 |
<param id="processor_count_ptr"> |
|
10412 |
<outptr><jint/></outptr> |
|
10413 |
<description> |
|
10414 |
On return, points to the maximum number of processors available to the |
|
10415 |
virtual machine; never smaller than one. |
|
10416 |
</description> |
|
10417 |
</param> |
|
10418 |
</parameters> |
|
10419 |
<errors> |
|
10420 |
</errors> |
|
10421 |
</function> |
|
10422 |
||
10423 |
</category> |
|
10424 |
||
10425 |
||
10426 |
<category id="classLoaderSearch" label="Class Loader Search"> |
|
10427 |
||
10428 |
<intro> |
|
10429 |
These functions allow the agent to add to the locations that a class loader searches for a class. |
|
10430 |
This is useful for installing instrumentation under the correct class loader. |
|
10431 |
</intro> |
|
10432 |
||
10433 |
<function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149"> |
|
10434 |
<synopsis>Add To Bootstrap Class Loader Search</synopsis> |
|
10435 |
<description> |
|
10436 |
This function can be used to cause instrumentation classes to be defined by the |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
10437 |
bootstrap class loader. See <vmspec chapter="5.3.1"/>. |
1 | 10438 |
After the bootstrap |
10439 |
class loader unsuccessfully searches for a class, the specified platform-dependent |
|
10440 |
search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in |
|
10441 |
the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, |
|
10442 |
the segments will be searched in the order that this function was called. |
|
10443 |
<p/> |
|
10444 |
In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent |
|
10445 |
search path segment to be searched after the bootstrap class loader unsuccessfully searches |
|
10446 |
for a class. The segment is typically a directory or JAR file. |
|
10447 |
<p/> |
|
10448 |
In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent |
|
14287 | 10449 |
path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html"> |
1 | 10450 |
JAR file</externallink>. The agent should take care that the JAR file does not |
10451 |
contain any classes or resources other than those to be defined by the bootstrap |
|
10452 |
class loader for the purposes of instrumentation. |
|
10453 |
<p/> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
10454 |
<vmspec/> specifies that a subsequent attempt to resolve a symbolic |
1 | 10455 |
reference that the Java virtual machine has previously unsuccessfully attempted |
10456 |
to resolve always fails with the same error that was thrown as a result of the |
|
10457 |
initial resolution attempt. Consequently, if the JAR file contains an entry |
|
10458 |
that corresponds to a class for which the Java virtual machine has |
|
10459 |
unsuccessfully attempted to resolve a reference, then subsequent attempts to |
|
10460 |
resolve that reference will fail with the same error as the initial attempt. |
|
10461 |
</description> |
|
10462 |
<origin>new</origin> |
|
10463 |
<capabilities> |
|
10464 |
</capabilities> |
|
10465 |
<parameters> |
|
10466 |
<param id="segment"> |
|
10467 |
<inbuf><char/></inbuf> |
|
10468 |
<description> |
|
10469 |
The platform-dependent search path segment, encoded as a |
|
10470 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
10471 |
</description> |
|
10472 |
</param> |
|
10473 |
</parameters> |
|
10474 |
<errors> |
|
10475 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
10476 |
<paramlink id="segment"/> is an invalid path. In the live phase, anything other than an |
|
10477 |
existing JAR file is an invalid path. |
|
10478 |
</error> |
|
10479 |
</errors> |
|
10480 |
</function> |
|
10481 |
||
10482 |
<function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1"> |
|
10483 |
<synopsis>Add To System Class Loader Search</synopsis> |
|
10484 |
<description> |
|
10485 |
This function can be used to cause instrumentation classes to be |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
10486 |
defined by the system class loader. See <vmspec chapter="5.3.2"/>. |
1 | 10487 |
After the class loader unsuccessfully searches for a class, the specified platform-dependent search |
10488 |
path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the |
|
10489 |
<paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the |
|
10490 |
segments will be searched in the order that this function was called. |
|
10491 |
<p/> |
|
10492 |
In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent |
|
10493 |
search path segment to be searched after the system class loader unsuccessfully searches |
|
10494 |
for a class. The segment is typically a directory or JAR file. |
|
10495 |
<p/> |
|
10496 |
In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink |
|
14287 | 10497 |
id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be |
1 | 10498 |
searched after the system class loader unsuccessfully searches for a class. The agent should |
10499 |
take care that the JAR file does not contain any classes or resources other than those to be |
|
10500 |
defined by the system class loader for the purposes of instrumentation. |
|
10501 |
<p/> |
|
10502 |
In the live phase the system class loader supports adding a JAR file to be searched if |
|
10503 |
the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> |
|
10504 |
which takes a single parameter of type <code>java.lang.String</code>. The method is not required |
|
10505 |
to have <code>public</code> access. |
|
10506 |
<p/> |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
10507 |
<vmspec/> specifies that a subsequent attempt to resolve a symbolic |
1 | 10508 |
reference that the Java virtual machine has previously unsuccessfully attempted |
10509 |
to resolve always fails with the same error that was thrown as a result of the |
|
10510 |
initial resolution attempt. Consequently, if the JAR file contains an entry |
|
10511 |
that corresponds to a class for which the Java virtual machine has |
|
10512 |
unsuccessfully attempted to resolve a reference, then subsequent attempts to |
|
10513 |
resolve that reference will fail with the same error as the initial attempt. |
|
10514 |
</description> |
|
10515 |
<origin>new</origin> |
|
10516 |
<capabilities> |
|
10517 |
</capabilities> |
|
10518 |
<parameters> |
|
10519 |
<param id="segment"> |
|
10520 |
<inbuf><char/></inbuf> |
|
10521 |
<description> |
|
10522 |
The platform-dependent search path segment, encoded as a |
|
10523 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
10524 |
</description> |
|
10525 |
</param> |
|
10526 |
</parameters> |
|
10527 |
<errors> |
|
10528 |
<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> |
|
10529 |
<paramlink id="segment"/> is an invalid path. In the live phase, anything other than an |
|
10530 |
existing JAR file is an invalid path. |
|
10531 |
</error> |
|
10532 |
<error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED"> |
|
10533 |
Operation not supported by the system class loader. |
|
10534 |
</error> |
|
10535 |
</errors> |
|
10536 |
</function> |
|
10537 |
||
10538 |
</category> |
|
10539 |
||
10540 |
||
10541 |
<category id="props" label="System Properties"> |
|
10542 |
||
10543 |
<intro> |
|
10544 |
These functions get and set system properties. |
|
10545 |
</intro> |
|
10546 |
||
10547 |
<function id="GetSystemProperties" phase="onload" num="130"> |
|
10548 |
<synopsis>Get System Properties</synopsis> |
|
10549 |
<description> |
|
10550 |
The list of VM system property keys which may be used with |
|
10551 |
<functionlink id="GetSystemProperty"/> is returned. |
|
10552 |
It is strongly recommended that virtual machines provide the |
|
10553 |
following property keys: |
|
10554 |
<ul> |
|
10555 |
<li><code>java.vm.vendor</code></li> |
|
10556 |
<li><code>java.vm.version</code></li> |
|
10557 |
<li><code>java.vm.name</code></li> |
|
10558 |
<li><code>java.vm.info</code></li> |
|
10559 |
<li><code>java.library.path</code></li> |
|
10560 |
<li><code>java.class.path</code></li> |
|
10561 |
</ul> |
|
10562 |
Provides access to system properties defined by and used |
|
10563 |
by the VM. |
|
10564 |
Properties set on the command-line are included. |
|
10565 |
This allows getting and setting of these properties |
|
10566 |
before the VM even begins executing bytecodes. |
|
10567 |
Since this is a VM view of system properties, the set of available |
|
10568 |
properties will usually be different than that |
|
10569 |
in <code>java.lang.System.getProperties</code>. |
|
10570 |
JNI method invocation may be used to access |
|
10571 |
<code>java.lang.System.getProperties</code>. |
|
10572 |
<p/> |
|
10573 |
The set of properties may grow during execution. |
|
10574 |
</description> |
|
10575 |
<origin>new</origin> |
|
10576 |
<capabilities> |
|
10577 |
</capabilities> |
|
10578 |
<parameters> |
|
10579 |
<param id="count_ptr"> |
|
10580 |
<outptr><jint/></outptr> |
|
10581 |
<description> |
|
10582 |
On return, points to the number of property keys returned. |
|
10583 |
</description> |
|
10584 |
</param> |
|
10585 |
<param id="property_ptr"> |
|
10586 |
<allocallocbuf outcount="count_ptr"><char/></allocallocbuf> |
|
10587 |
<description> |
|
10588 |
On return, points to an array of property keys, encoded as |
|
10589 |
<internallink id="mUTF">modified UTF-8</internallink> strings. |
|
10590 |
</description> |
|
10591 |
</param> |
|
10592 |
</parameters> |
|
10593 |
<errors> |
|
10594 |
</errors> |
|
10595 |
</function> |
|
10596 |
||
10597 |
<function id="GetSystemProperty" phase="onload" num="131"> |
|
10598 |
<synopsis>Get System Property</synopsis> |
|
10599 |
<description> |
|
10600 |
Return a VM system property value given the property key. |
|
10601 |
<p/> |
|
10602 |
The function <functionlink id="GetSystemProperties"/> |
|
10603 |
returns the set of property keys which may be used. |
|
10604 |
The properties which can be retrieved may grow during |
|
10605 |
execution. |
|
10606 |
<p/> |
|
10607 |
Since this is a VM view of system properties, the values |
|
10608 |
of properties may differ from that returned by |
|
10609 |
<code>java.lang.System.getProperty(String)</code>. |
|
10610 |
A typical VM might copy the values of the VM system |
|
10611 |
properties into the <code>Properties</code> held by |
|
10612 |
<code>java.lang.System</code> during the initialization |
|
10613 |
of that class. Thereafter any changes to the VM system |
|
10614 |
properties (with <functionlink id="SetSystemProperty"/>) |
|
10615 |
or the <code>java.lang.System</code> system properties |
|
10616 |
(with <code>java.lang.System.setProperty(String,String)</code>) |
|
10617 |
would cause the values to diverge. |
|
10618 |
JNI method invocation may be used to access |
|
10619 |
<code>java.lang.System.getProperty(String)</code>. |
|
10620 |
</description> |
|
10621 |
<origin>new</origin> |
|
10622 |
<capabilities> |
|
10623 |
</capabilities> |
|
10624 |
<parameters> |
|
10625 |
<param id="property"> |
|
10626 |
<inbuf><char/></inbuf> |
|
10627 |
<description> |
|
10628 |
The key of the property to retrieve, encoded as a |
|
10629 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
10630 |
</description> |
|
10631 |
</param> |
|
10632 |
<param id="value_ptr"> |
|
10633 |
<allocbuf><char/></allocbuf> |
|
10634 |
<description> |
|
10635 |
On return, points to the property value, encoded as a |
|
10636 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
10637 |
</description> |
|
10638 |
</param> |
|
10639 |
</parameters> |
|
10640 |
<errors> |
|
10641 |
<error id="JVMTI_ERROR_NOT_AVAILABLE"> |
|
10642 |
This property is not available. |
|
10643 |
Use <functionlink id="GetSystemProperties"/> to find available properties. |
|
10644 |
</error> |
|
10645 |
</errors> |
|
10646 |
</function> |
|
10647 |
||
10648 |
<function id="SetSystemProperty" phase="onloadOnly" num="132"> |
|
10649 |
<synopsis>Set System Property</synopsis> |
|
10650 |
<description> |
|
10651 |
Set a VM system property value. |
|
10652 |
<p/> |
|
10653 |
The function <functionlink id="GetSystemProperties"/> |
|
10654 |
returns the set of property keys, some of these may be settable. |
|
10655 |
See <functionlink id="GetSystemProperty"/>. |
|
10656 |
</description> |
|
10657 |
<origin>new</origin> |
|
10658 |
<capabilities> |
|
10659 |
</capabilities> |
|
10660 |
<parameters> |
|
10661 |
<param id="property"> |
|
10662 |
<inbuf><char/></inbuf> |
|
10663 |
<description> |
|
10664 |
The key of the property, encoded as a |
|
10665 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
10666 |
</description> |
|
10667 |
</param> |
|
7724
a92d706dbdd5
7003271: Hotspot should track cumulative Java heap bytes allocated on a per-thread basis
phh
parents:
7444
diff
changeset
|
10668 |
<param id="value_ptr"> |
1 | 10669 |
<inbuf> |
10670 |
<char/> |
|
10671 |
<nullok> |
|
10672 |
do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/> |
|
10673 |
if the property is not writeable |
|
10674 |
</nullok> |
|
10675 |
</inbuf> |
|
10676 |
<description> |
|
10677 |
The property value to set, encoded as a |
|
10678 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
10679 |
</description> |
|
10680 |
</param> |
|
10681 |
</parameters> |
|
10682 |
<errors> |
|
10683 |
<error id="JVMTI_ERROR_NOT_AVAILABLE"> |
|
10684 |
This property is not available or is not writeable. |
|
10685 |
</error> |
|
10686 |
</errors> |
|
10687 |
</function> |
|
10688 |
||
10689 |
</category> |
|
10690 |
||
10691 |
<category id="general" label="General"> |
|
10692 |
||
10693 |
<intro> |
|
10694 |
</intro> |
|
10695 |
||
10696 |
<function id="GetPhase" jkernel="yes" phase="any" num="133"> |
|
10697 |
<synopsis>Get Phase</synopsis> |
|
10698 |
<description> |
|
10699 |
Return the current phase of VM execution. |
|
10700 |
The phases proceed in sequence: |
|
10701 |
<constants id="jvmtiPhase" label="Phases of execution" kind="enum"> |
|
10702 |
<constant id="JVMTI_PHASE_ONLOAD" num="1"> |
|
10703 |
<code>OnLoad</code> phase: while in the |
|
10704 |
<internallink id="onload"><code>Agent_OnLoad</code></internallink> function. |
|
10705 |
</constant> |
|
10706 |
<constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> |
|
10707 |
Primordial phase: between return from <code>Agent_OnLoad</code> and the |
|
10708 |
<code>VMStart</code> event. |
|
10709 |
</constant> |
|
10710 |
<constant id="JVMTI_PHASE_START" num="6"> |
|
10711 |
Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event |
|
10712 |
is sent and until the <code>VMInit</code> event is sent. |
|
10713 |
</constant> |
|
10714 |
<constant id="JVMTI_PHASE_LIVE" num="4"> |
|
10715 |
Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent |
|
10716 |
and until the <eventlink id="VMDeath"></eventlink> event returns. |
|
10717 |
</constant> |
|
10718 |
<constant id="JVMTI_PHASE_DEAD" num="8"> |
|
10719 |
Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after |
|
10720 |
start-up failure. |
|
10721 |
</constant> |
|
10722 |
</constants> |
|
10723 |
In the case of start-up failure the VM will proceed directly to the dead |
|
10724 |
phase skipping intermediate phases and neither a <code>VMInit</code> nor |
|
10725 |
<code>VMDeath</code> event will be sent. |
|
10726 |
<p/> |
|
10727 |
Most <jvmti/> functions operate only in the live phase. |
|
10728 |
The following functions operate in either the <code>OnLoad</code> or live phases: |
|
10729 |
<functionphaselist phase="onload"/> |
|
10730 |
The following functions operate in only the <code>OnLoad</code> phase: |
|
10731 |
<functionphaselist phase="onloadOnly"/> |
|
10732 |
The following functions operate in the start or live phases: |
|
10733 |
<functionphaselist phase="start"/> |
|
10734 |
The following functions operate in any phase: |
|
10735 |
<functionphaselist phase="any"/> |
|
10736 |
JNI functions (except the Invocation API) must only be used in the start or live phases. |
|
10737 |
<p/> |
|
10738 |
Most <jvmti/> events are sent only in the live phase. |
|
10739 |
The following events operate in others phases: |
|
10740 |
<eventphaselist phase="start"/> |
|
10741 |
<eventphaselist phase="any"/> |
|
10742 |
</description> |
|
10743 |
<origin>new</origin> |
|
10744 |
<capabilities> |
|
10745 |
</capabilities> |
|
10746 |
<parameters> |
|
10747 |
<param id="phase_ptr"> |
|
10748 |
<outptr><enum>jvmtiPhase</enum></outptr> |
|
10749 |
<description> |
|
10750 |
On return, points to the phase. |
|
10751 |
</description> |
|
10752 |
</param> |
|
10753 |
</parameters> |
|
10754 |
<errors> |
|
10755 |
</errors> |
|
10756 |
</function> |
|
10757 |
||
10758 |
<function id="DisposeEnvironment" jkernel="yes" phase="any" num="127"> |
|
10759 |
<synopsis>Dispose Environment</synopsis> |
|
10760 |
<description> |
|
10761 |
Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code> |
|
10762 |
(see <internallink id="environments"><jvmti/> Environments</internallink>). |
|
10763 |
Dispose of any resources held by the environment. |
|
10764 |
<issue> |
|
10765 |
What resources are reclaimed? What is undone? |
|
10766 |
Breakpoints,watchpoints removed? |
|
10767 |
</issue> |
|
10768 |
Threads suspended by this environment are not resumed by this call, |
|
10769 |
this must be done explicitly by the agent. |
|
10770 |
Memory allocated by this environment via calls to <jvmti/> functions |
|
10771 |
is not released, this can be done explicitly by the agent |
|
10772 |
by calling <functionlink id="Deallocate"/>. |
|
10773 |
Raw monitors created by this environment are not destroyed, |
|
10774 |
this can be done explicitly by the agent |
|
10775 |
by calling <functionlink id="DestroyRawMonitor"/>. |
|
10776 |
The state of threads waiting on raw monitors created by this environment |
|
10777 |
are not affected. |
|
10778 |
<p/> |
|
10779 |
Any <functionlink id="SetNativeMethodPrefix">native method |
|
10780 |
prefixes</functionlink> for this environment will be unset; |
|
10781 |
the agent must remove any prefixed native methods before |
|
10782 |
dispose is called. |
|
10783 |
<p/> |
|
10784 |
Any <internallink id="capability">capabilities</internallink> |
|
10785 |
held by this environment are relinquished. |
|
10786 |
<p/> |
|
10787 |
Events enabled by this environment will no longer be sent, however |
|
10788 |
event handlers currently running will continue to run. Caution must |
|
10789 |
be exercised in the design of event handlers whose environment may |
|
10790 |
be disposed and thus become invalid during their execution. |
|
10791 |
<p/> |
|
10792 |
This environment may not be used after this call. |
|
10793 |
This call returns to the caller. |
|
10794 |
</description> |
|
10795 |
<origin>new</origin> |
|
10796 |
<capabilities> |
|
10797 |
</capabilities> |
|
10798 |
<parameters> |
|
10799 |
</parameters> |
|
10800 |
<errors> |
|
10801 |
</errors> |
|
10802 |
</function> |
|
10803 |
||
10804 |
<function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148"> |
|
10805 |
<synopsis>Set Environment Local Storage</synopsis> |
|
10806 |
<description> |
|
10807 |
The VM stores a pointer value associated with each environment. |
|
10808 |
This pointer value is called <i>environment-local storage</i>. |
|
10809 |
This value is <code>NULL</code> unless set with this function. |
|
10810 |
Agents can allocate memory in which they store environment specific |
|
10811 |
information. By setting environment-local storage it can then be |
|
10812 |
accessed with |
|
10813 |
<functionlink id="GetEnvironmentLocalStorage"></functionlink>. |
|
10814 |
<p/> |
|
10815 |
Called by the agent to set the value of the <jvmti/> |
|
10816 |
environment-local storage. <jvmti/> supplies to the agent a pointer-size |
|
10817 |
environment-local storage that can be used to record per-environment |
|
10818 |
information. |
|
10819 |
</description> |
|
10820 |
<origin>new</origin> |
|
10821 |
<capabilities> |
|
10822 |
</capabilities> |
|
10823 |
<parameters> |
|
10824 |
<param id="data"> |
|
10825 |
<inbuf> |
|
10826 |
<void/> |
|
10827 |
<nullok>value is set to <code>NULL</code></nullok> |
|
10828 |
</inbuf> |
|
10829 |
<description> |
|
10830 |
The value to be entered into the environment-local storage. |
|
10831 |
</description> |
|
10832 |
</param> |
|
10833 |
</parameters> |
|
10834 |
<errors> |
|
10835 |
</errors> |
|
10836 |
</function> |
|
10837 |
||
10838 |
<function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147"> |
|
10839 |
<synopsis>Get Environment Local Storage</synopsis> |
|
10840 |
<description> |
|
10841 |
Called by the agent to get the value of the <jvmti/> environment-local |
|
10842 |
storage. |
|
10843 |
</description> |
|
10844 |
<origin>new</origin> |
|
10845 |
<capabilities> |
|
10846 |
</capabilities> |
|
10847 |
<parameters> |
|
10848 |
<param id="data_ptr"> |
|
10849 |
<agentbuf><void/></agentbuf> |
|
10850 |
<description> |
|
10851 |
Pointer through which the value of the environment local |
|
10852 |
storage is returned. |
|
10853 |
If environment-local storage has not been set with |
|
10854 |
<functionlink id="SetEnvironmentLocalStorage"></functionlink> returned |
|
10855 |
pointer is <code>NULL</code>. |
|
10856 |
</description> |
|
10857 |
</param> |
|
10858 |
</parameters> |
|
10859 |
<errors> |
|
10860 |
</errors> |
|
10861 |
</function> |
|
10862 |
||
10863 |
<function id="GetVersionNumber" jkernel="yes" phase="any" num="88"> |
|
10864 |
<synopsis>Get Version Number</synopsis> |
|
10865 |
<description> |
|
10866 |
Return the <jvmti/> version via <code>version_ptr</code>. |
|
10867 |
The return value is the version identifier. |
|
10868 |
The version identifier includes major, minor and micro |
|
10869 |
version as well as the interface type. |
|
10870 |
<constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits"> |
|
10871 |
<constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000"> |
|
10872 |
Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI. |
|
10873 |
</constant> |
|
10874 |
<constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000"> |
|
10875 |
Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>. |
|
10876 |
</constant> |
|
10877 |
</constants> |
|
10878 |
<constants id="jvmtiVersionMasks" label="Version Masks" kind="bits"> |
|
10879 |
<constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000"> |
|
10880 |
Mask to extract interface type. |
|
10881 |
The value of the version returned by this function masked with |
|
10882 |
<code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always |
|
10883 |
<code>JVMTI_VERSION_INTERFACE_JVMTI</code> |
|
10884 |
since this is a <jvmti/> function. |
|
10885 |
</constant> |
|
10886 |
<constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000"> |
|
10887 |
Mask to extract major version number. |
|
10888 |
</constant> |
|
10889 |
<constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00"> |
|
10890 |
Mask to extract minor version number. |
|
10891 |
</constant> |
|
10892 |
<constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF"> |
|
10893 |
Mask to extract micro version number. |
|
10894 |
</constant> |
|
10895 |
</constants> |
|
10896 |
<constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits"> |
|
10897 |
<constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16"> |
|
10898 |
Shift to extract major version number. |
|
10899 |
</constant> |
|
10900 |
<constant id="JVMTI_VERSION_SHIFT_MINOR" num="8"> |
|
10901 |
Shift to extract minor version number. |
|
10902 |
</constant> |
|
10903 |
<constant id="JVMTI_VERSION_SHIFT_MICRO" num="0"> |
|
10904 |
Shift to extract micro version number. |
|
10905 |
</constant> |
|
10906 |
</constants> |
|
10907 |
</description> |
|
10908 |
<origin>jvmdi</origin> |
|
10909 |
<capabilities> |
|
10910 |
</capabilities> |
|
10911 |
<parameters> |
|
10912 |
<param id="version_ptr"> |
|
10913 |
<outptr><jint/></outptr> |
|
10914 |
<description> |
|
10915 |
On return, points to the <jvmti/> version. |
|
10916 |
</description> |
|
10917 |
</param> |
|
10918 |
</parameters> |
|
10919 |
<errors> |
|
10920 |
</errors> |
|
10921 |
</function> |
|
10922 |
||
10923 |
||
10924 |
<function id="GetErrorName" phase="any" num="128"> |
|
10925 |
<synopsis>Get Error Name</synopsis> |
|
10926 |
<description> |
|
10927 |
Return the symbolic name for an |
|
10928 |
<internallink id="ErrorSection">error code</internallink>. |
|
10929 |
<p/> |
|
10930 |
For example |
|
10931 |
<code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code> |
|
10932 |
would return in <code>err_name</code> the string |
|
10933 |
<code>"JVMTI_ERROR_NONE"</code>. |
|
10934 |
</description> |
|
10935 |
<origin>new</origin> |
|
10936 |
<capabilities> |
|
10937 |
</capabilities> |
|
10938 |
<parameters> |
|
10939 |
<param id="error"> |
|
10940 |
<enum>jvmtiError</enum> |
|
10941 |
<description> |
|
10942 |
The error code. |
|
10943 |
</description> |
|
10944 |
</param> |
|
10945 |
<param id="name_ptr"> |
|
10946 |
<allocbuf><char/></allocbuf> |
|
10947 |
<description> |
|
10948 |
On return, points to the error name. |
|
10949 |
The name is encoded as a |
|
10950 |
<internallink id="mUTF">modified UTF-8</internallink> string, |
|
10951 |
but is restricted to the ASCII subset. |
|
10952 |
</description> |
|
10953 |
</param> |
|
10954 |
</parameters> |
|
10955 |
<errors> |
|
10956 |
</errors> |
|
10957 |
</function> |
|
10958 |
||
10959 |
<function id="SetVerboseFlag" phase="any" num="150"> |
|
10960 |
<synopsis>Set Verbose Flag</synopsis> |
|
10961 |
<description> |
|
10962 |
<constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum"> |
|
10963 |
<constant id="JVMTI_VERBOSE_OTHER" num="0"> |
|
10964 |
Verbose output other than the below. |
|
10965 |
</constant> |
|
10966 |
<constant id="JVMTI_VERBOSE_GC" num="1"> |
|
10967 |
Verbose garbage collector output, like that specified with <code>-verbose:gc</code>. |
|
10968 |
</constant> |
|
10969 |
<constant id="JVMTI_VERBOSE_CLASS" num="2"> |
|
10970 |
Verbose class loading output, like that specified with <code>-verbose:class</code>. |
|
10971 |
</constant> |
|
10972 |
<constant id="JVMTI_VERBOSE_JNI" num="4"> |
|
10973 |
Verbose JNI output, like that specified with <code>-verbose:jni</code>. |
|
10974 |
</constant> |
|
10975 |
</constants> |
|
10976 |
Control verbose output. |
|
10977 |
This is the output which typically is sent to <code>stderr</code>. |
|
10978 |
</description> |
|
10979 |
<origin>new</origin> |
|
10980 |
<capabilities> |
|
10981 |
</capabilities> |
|
10982 |
<parameters> |
|
10983 |
<param id="flag"> |
|
10984 |
<enum>jvmtiVerboseFlag</enum> |
|
10985 |
<description> |
|
10986 |
Which verbose flag to set. |
|
10987 |
</description> |
|
10988 |
</param> |
|
10989 |
<param id="value"> |
|
10990 |
<jboolean/> |
|
10991 |
<description> |
|
10992 |
New value of the flag. |
|
10993 |
</description> |
|
10994 |
</param> |
|
10995 |
</parameters> |
|
10996 |
<errors> |
|
10997 |
</errors> |
|
10998 |
</function> |
|
10999 |
||
11000 |
||
11001 |
<function id="GetJLocationFormat" phase="any" num="129"> |
|
11002 |
<synopsis>Get JLocation Format</synopsis> |
|
11003 |
<description> |
|
11004 |
Although the greatest functionality is achieved with location information |
|
11005 |
referencing the virtual machine bytecode index, the definition of |
|
11006 |
<code>jlocation</code> has intentionally been left unconstrained to allow VM |
|
11007 |
implementations that do not have this information. |
|
11008 |
<p/> |
|
11009 |
This function describes the representation of <code>jlocation</code> used in this VM. |
|
11010 |
If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, |
|
11011 |
<code>jlocation</code>s can |
|
11012 |
be used as in indices into the array returned by |
|
11013 |
<functionlink id="GetBytecodes"></functionlink>. |
|
11014 |
<constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum"> |
|
11015 |
<constant id="JVMTI_JLOCATION_JVMBCI" num="1"> |
|
11016 |
<code>jlocation</code> values represent virtual machine |
|
11017 |
bytecode indices--that is, offsets into the |
|
11018 |
virtual machine code for a method. |
|
11019 |
</constant> |
|
11020 |
<constant id="JVMTI_JLOCATION_MACHINEPC" num="2"> |
|
11021 |
<code>jlocation</code> values represent native machine |
|
11022 |
program counter values. |
|
11023 |
</constant> |
|
11024 |
<constant id="JVMTI_JLOCATION_OTHER" num="0"> |
|
11025 |
<code>jlocation</code> values have some other representation. |
|
11026 |
</constant> |
|
11027 |
</constants> |
|
11028 |
</description> |
|
11029 |
<origin>new</origin> |
|
11030 |
<capabilities> |
|
11031 |
</capabilities> |
|
11032 |
<parameters> |
|
11033 |
<param id="format_ptr"> |
|
11034 |
<outptr><enum>jvmtiJlocationFormat</enum></outptr> |
|
11035 |
<description> |
|
11036 |
On return, points to the format identifier for <code>jlocation</code> values. |
|
11037 |
</description> |
|
11038 |
</param> |
|
11039 |
</parameters> |
|
11040 |
<errors> |
|
11041 |
</errors> |
|
11042 |
</function> |
|
11043 |
||
11044 |
</category> |
|
11045 |
||
11046 |
</functionsection> |
|
11047 |
||
11048 |
<errorsection label="Error Reference"> |
|
11049 |
<intro> |
|
11050 |
Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code. |
|
11051 |
<p/> |
|
11052 |
It is the responsibility of the agent to call <jvmti/> functions with |
|
11053 |
valid parameters and in the proper context (calling thread is attached, |
|
11054 |
phase is correct, etc.). |
|
11055 |
Detecting some error conditions may be difficult, inefficient, or |
|
11056 |
impossible for an implementation. |
|
11057 |
The errors listed in |
|
11058 |
<internallink id="reqerrors">Function Specific Required Errors</internallink> |
|
11059 |
must be detected by the implementation. |
|
11060 |
All other errors represent the recommended response to the error |
|
11061 |
condition. |
|
11062 |
</intro> |
|
11063 |
||
11064 |
<errorcategory id="universal-error" label="Universal Errors"> |
|
11065 |
<intro> |
|
11066 |
The following errors may be returned by any function |
|
11067 |
</intro> |
|
11068 |
||
11069 |
<errorid id="JVMTI_ERROR_NONE" num="0"> |
|
11070 |
No error has occurred. This is the error code that is returned |
|
11071 |
on successful completion of the function. |
|
11072 |
</errorid> |
|
11073 |
<errorid id="JVMTI_ERROR_NULL_POINTER" num="100"> |
|
11074 |
Pointer is unexpectedly <code>NULL</code>. |
|
11075 |
</errorid> |
|
11076 |
<errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110"> |
|
11077 |
The function attempted to allocate memory and no more memory was |
|
11078 |
available for allocation. |
|
11079 |
</errorid> |
|
11080 |
<errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111"> |
|
11081 |
The desired functionality has not been enabled in this virtual machine. |
|
11082 |
</errorid> |
|
11083 |
<errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115"> |
|
11084 |
The thread being used to call this function is not attached |
|
11085 |
to the virtual machine. Calls must be made from attached threads. |
|
11086 |
See <code>AttachCurrentThread</code> in the JNI invocation API. |
|
11087 |
</errorid> |
|
11088 |
<errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116"> |
|
11089 |
The <jvmti/> environment provided is no longer connected or is |
|
11090 |
not an environment. |
|
11091 |
</errorid> |
|
11092 |
<errorid id="JVMTI_ERROR_WRONG_PHASE" num="112"> |
|
11093 |
The desired functionality is not available in the current |
|
11094 |
<functionlink id="GetPhase">phase</functionlink>. |
|
11095 |
Always returned if the virtual machine has completed running. |
|
11096 |
</errorid> |
|
11097 |
<errorid id="JVMTI_ERROR_INTERNAL" num="113"> |
|
11098 |
An unexpected internal error has occurred. |
|
11099 |
</errorid> |
|
11100 |
</errorcategory> |
|
11101 |
||
11102 |
<errorcategory id="reqerrors" label="Function Specific Required Errors"> |
|
11103 |
<intro> |
|
11104 |
The following errors are returned by some <jvmti/> functions and must |
|
11105 |
be returned by the implementation when the condition occurs. |
|
11106 |
</intro> |
|
11107 |
||
11108 |
<errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12"> |
|
11109 |
Invalid priority. |
|
11110 |
</errorid> |
|
11111 |
<errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13"> |
|
11112 |
Thread was not suspended. |
|
11113 |
</errorid> |
|
11114 |
<errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14"> |
|
11115 |
Thread already suspended. |
|
11116 |
</errorid> |
|
11117 |
<errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15"> |
|
11118 |
This operation requires the thread to be alive--that is, |
|
11119 |
it must be started and not yet have died. |
|
11120 |
</errorid> |
|
11121 |
<errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22"> |
|
11122 |
The class has been loaded but not yet prepared. |
|
11123 |
</errorid> |
|
11124 |
<errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31"> |
|
11125 |
There are no Java programming language or JNI stack frames at the specified depth. |
|
11126 |
</errorid> |
|
11127 |
<errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32"> |
|
11128 |
Information about the frame is not available (e.g. for native frames). |
|
11129 |
</errorid> |
|
11130 |
<errorid id="JVMTI_ERROR_DUPLICATE" num="40"> |
|
11131 |
Item already set. |
|
11132 |
</errorid> |
|
11133 |
<errorid id="JVMTI_ERROR_NOT_FOUND" num="41"> |
|
11134 |
Desired element (e.g. field or breakpoint) not found |
|
11135 |
</errorid> |
|
11136 |
<errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51"> |
|
11137 |
This thread doesn't own the raw monitor. |
|
11138 |
</errorid> |
|
11139 |
<errorid id="JVMTI_ERROR_INTERRUPT" num="52"> |
|
11140 |
The call has been interrupted before completion. |
|
11141 |
</errorid> |
|
11142 |
<errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79"> |
|
11143 |
The class cannot be modified. |
|
11144 |
</errorid> |
|
11145 |
<errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98"> |
|
11146 |
The functionality is not available in this virtual machine. |
|
11147 |
</errorid> |
|
11148 |
<errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101"> |
|
11149 |
The requested information is not available. |
|
11150 |
</errorid> |
|
11151 |
<errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102"> |
|
11152 |
The specified event type ID is not recognized. |
|
11153 |
</errorid> |
|
11154 |
<errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104"> |
|
11155 |
The requested information is not available for native method. |
|
11156 |
</errorid> |
|
11157 |
<errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106"> |
|
11158 |
The class loader does not support this operation. |
|
11159 |
</errorid> |
|
11160 |
</errorcategory> |
|
11161 |
||
11162 |
<errorcategory id="function-specific-errors" label="Function Specific Agent Errors"> |
|
11163 |
<intro> |
|
11164 |
The following errors are returned by some <jvmti/> functions. |
|
11165 |
They are returned in the event of invalid parameters passed by the |
|
11166 |
agent or usage in an invalid context. |
|
11167 |
An implementation is not required to detect these errors. |
|
11168 |
</intro> |
|
11169 |
||
11170 |
<errorid id="JVMTI_ERROR_INVALID_THREAD" num="10"> |
|
11171 |
The passed thread is not a valid thread. |
|
11172 |
</errorid> |
|
11173 |
<errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25"> |
|
11174 |
Invalid field. |
|
11175 |
</errorid> |
|
11176 |
<errorid id="JVMTI_ERROR_INVALID_METHODID" num="23"> |
|
11177 |
Invalid method. |
|
11178 |
</errorid> |
|
11179 |
<errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24"> |
|
11180 |
Invalid location. |
|
11181 |
</errorid> |
|
11182 |
<errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20"> |
|
11183 |
Invalid object. |
|
11184 |
</errorid> |
|
11185 |
<errorid id="JVMTI_ERROR_INVALID_CLASS" num="21"> |
|
11186 |
Invalid class. |
|
11187 |
</errorid> |
|
11188 |
<errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34"> |
|
11189 |
The variable is not an appropriate type for the function used. |
|
11190 |
</errorid> |
|
11191 |
<errorid id="JVMTI_ERROR_INVALID_SLOT" num="35"> |
|
11192 |
Invalid slot. |
|
11193 |
</errorid> |
|
11194 |
<errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99"> |
|
11195 |
The capability being used is false in this environment. |
|
11196 |
</errorid> |
|
11197 |
<errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11"> |
|
11198 |
Thread group invalid. |
|
11199 |
</errorid> |
|
11200 |
<errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50"> |
|
11201 |
Invalid raw monitor. |
|
11202 |
</errorid> |
|
11203 |
<errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103"> |
|
11204 |
Illegal argument. |
|
11205 |
</errorid> |
|
11206 |
<errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65"> |
|
11207 |
The state of the thread has been modified, and is now inconsistent. |
|
11208 |
</errorid> |
|
11209 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68"> |
|
11210 |
A new class file has a version number not supported by this VM. |
|
11211 |
</errorid> |
|
11212 |
<errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60"> |
|
11213 |
A new class file is malformed (the VM would return a <code>ClassFormatError</code>). |
|
11214 |
</errorid> |
|
11215 |
<errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61"> |
|
11216 |
The new class file definitions would lead to a circular |
|
11217 |
definition (the VM would return a <code>ClassCircularityError</code>). |
|
11218 |
</errorid> |
|
11219 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63"> |
|
11220 |
A new class file would require adding a method. |
|
11221 |
</errorid> |
|
11222 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64"> |
|
11223 |
A new class version changes a field. |
|
11224 |
</errorid> |
|
11225 |
<errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62"> |
|
11226 |
The class bytes fail verification. |
|
11227 |
</errorid> |
|
11228 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66"> |
|
11229 |
A direct superclass is different for the new class |
|
11230 |
version, or the set of directly implemented |
|
11231 |
interfaces is different. |
|
11232 |
</errorid> |
|
11233 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67"> |
|
11234 |
A new class version does not declare a method |
|
11235 |
declared in the old class version. |
|
11236 |
</errorid> |
|
11237 |
<errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69"> |
|
11238 |
The class name defined in the new class file is |
|
11239 |
different from the name in the old class object. |
|
11240 |
</errorid> |
|
11241 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70"> |
|
11242 |
A new class version has different modifiers. |
|
11243 |
</errorid> |
|
11244 |
<errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71"> |
|
11245 |
A method in the new class version has different modifiers |
|
11246 |
than its counterpart in the old class version. |
|
11247 |
</errorid> |
|
11248 |
</errorcategory> |
|
11249 |
</errorsection> |
|
11250 |
||
11251 |
<eventsection label="Events"> |
|
11252 |
<intro label="Handling Events" id="eventIntro"> |
|
11253 |
Agents can be informed of many events that occur in application |
|
11254 |
programs. |
|
11255 |
<p/> |
|
11256 |
To handle events, designate a set of callback functions with |
|
11257 |
<functionlink id="SetEventCallbacks"></functionlink>. |
|
11258 |
For each event the corresponding callback function will be |
|
11259 |
called. |
|
11260 |
Arguments to the callback function provide additional |
|
11261 |
information about the event. |
|
11262 |
<p/> |
|
11263 |
The callback function is usually called from within an application |
|
11264 |
thread. The <jvmti/> implementation does not |
|
11265 |
queue events in any way. This means |
|
11266 |
that event callback functions must be written |
|
11267 |
carefully. Here are some general guidelines. See |
|
11268 |
the individual event descriptions for further |
|
11269 |
suggestions. |
|
11270 |
<p/> |
|
11271 |
<ul> |
|
11272 |
<li>Any exception thrown during the execution of an event callback can |
|
11273 |
overwrite any current pending exception in the current application thread. |
|
11274 |
Care must be taken to preserve a pending exception |
|
11275 |
when an event callback makes a JNI call that might generate an exception. |
|
11276 |
</li> |
|
11277 |
<li>Event callback functions must be re-entrant. The <jvmti/> implementation does |
|
11278 |
not queue events. If an agent needs to process events one at a time, it |
|
11279 |
can use a raw monitor inside the |
|
11280 |
event callback functions to serialize event processing. |
|
11281 |
</li> |
|
11282 |
<li>Event callback functions that execute JNI's FindClass function to load |
|
11283 |
classes need to note that FindClass locates the class loader associated |
|
11284 |
with the current native method. For the purposes of class loading, an |
|
11285 |
event callback that includes a JNI environment as a parameter to the |
|
11286 |
callback will treated as if it is a native call, where the native method |
|
11287 |
is in the class of the event thread's current frame. |
|
11288 |
</li> |
|
11289 |
</ul> |
|
11290 |
<p/> |
|
11291 |
Some <jvmti/> events identify objects with JNI references. |
|
11292 |
All references |
|
11293 |
in <jvmti/> events are JNI local references and will become invalid |
|
11294 |
after the event callback returns. |
|
11295 |
Unless stated otherwise, memory referenced by pointers sent in event |
|
11296 |
callbacks may not be referenced after the event callback returns. |
|
11297 |
<p/> |
|
11298 |
Except where stated otherwise, events are delivered on the thread |
|
11299 |
that caused the event. |
|
11300 |
Events are sent at the time they occur. |
|
11301 |
The specification for each event includes the set of |
|
11302 |
<functionlink id="GetPhase">phases</functionlink> in which it can be sent; |
|
11303 |
if an event triggering activity occurs during another phase, no event |
|
11304 |
is sent. |
|
11305 |
<p/> |
|
11306 |
A thread that generates an event does not change its execution status |
|
11307 |
(for example, the event does not cause the thread to be suspended). |
|
11308 |
If an agent wishes the event to result in suspension, then the agent |
|
11309 |
is responsible for explicitly suspending the thread with |
|
11310 |
<functionlink id="SuspendThread"></functionlink>. |
|
11311 |
<p/> |
|
11312 |
If an event is enabled in multiple environments, the event will be sent |
|
11313 |
to each agent in the order that the environments were created. |
|
11314 |
</intro> |
|
11315 |
||
11316 |
<intro label="Enabling Events" id="enablingevents"> |
|
11317 |
All events are initially disabled. In order to receive any |
|
11318 |
event: |
|
11319 |
<ul> |
|
11320 |
<li> |
|
11321 |
If the event requires a capability, that capability must |
|
11322 |
be added with |
|
11323 |
<functionlink id="AddCapabilities"></functionlink>. |
|
11324 |
</li> |
|
11325 |
<li> |
|
11326 |
A callback for the event must be set with |
|
11327 |
<functionlink id="SetEventCallbacks"></functionlink>. |
|
11328 |
</li> |
|
11329 |
<li> |
|
11330 |
The event must be enabled with |
|
11331 |
<functionlink id="SetEventNotificationMode"></functionlink>. |
|
11332 |
</li> |
|
11333 |
</ul> |
|
11334 |
</intro> |
|
11335 |
||
11336 |
<intro label="Multiple Co-located Events" id="eventorder"> |
|
11337 |
In many situations it is possible for multiple events to occur |
|
11338 |
at the same location in one thread. When this happens, all the events |
|
11339 |
are reported through the event callbacks in the order specified in this section. |
|
11340 |
<p/> |
|
11341 |
If the current location is at the entry point of a method, the |
|
11342 |
<eventlink id="MethodEntry"></eventlink> event is reported before |
|
11343 |
any other event at the current location in the same thread. |
|
11344 |
<p/> |
|
11345 |
If an exception catch has been detected at the current location, |
|
11346 |
either because it is the beginning of a catch clause or a native method |
|
11347 |
that cleared a pending exception has returned, the |
|
11348 |
<code>exceptionCatch</code> event is reported before |
|
11349 |
any other event at the current location in the same thread. |
|
11350 |
<p/> |
|
11351 |
If a <code>singleStep</code> event or |
|
11352 |
<code>breakpoint</code> event is triggered at the |
|
11353 |
current location, the event is defined to occur |
|
11354 |
immediately before the code at the current location is executed. |
|
11355 |
These events are reported before any events which are triggered |
|
11356 |
by the execution of code at the current location in the same |
|
11357 |
thread (specifically: |
|
11358 |
<code>exception</code>, |
|
11359 |
<code>fieldAccess</code>, and |
|
11360 |
<code>fieldModification</code>). |
|
11361 |
If both a step and breakpoint event are triggered for the same thread and |
|
11362 |
location, the step event is reported before the breakpoint event. |
|
11363 |
<p/> |
|
11364 |
If the current location is the exit point of a method (that is, the last |
|
11365 |
location before returning to the caller), the |
|
11366 |
<eventlink id="MethodExit"></eventlink> event and |
|
11367 |
the <eventlink id="FramePop"></eventlink> event (if requested) |
|
11368 |
are reported after all other events at the current location in the same |
|
11369 |
thread. There is no specified ordering of these two events |
|
11370 |
with respect to each other. |
|
11371 |
<p/> |
|
11372 |
Co-located events can be triggered during the processing of some other |
|
11373 |
event by the agent at the same location in the same thread. |
|
11374 |
If such an event, of type <i>y</i>, is triggered during the processing of |
|
11375 |
an event of type <i>x</i>, and if <i>x</i> |
|
11376 |
precedes <i>y</i> in the ordering specified above, the co-located event |
|
11377 |
<i>y</i> is reported for the current thread and location. If <i>x</i> does not precede |
|
11378 |
<i>y</i>, <i>y</i> is not reported for the current thread and location. |
|
11379 |
For example, if a breakpoint is set at the current location |
|
11380 |
during the processing of <eventlink id="SingleStep"></eventlink>, |
|
11381 |
that breakpoint will be reported before the thread moves off the current |
|
11382 |
location. |
|
11383 |
<p/>The following events are never considered to be co-located with |
|
11384 |
other events. |
|
11385 |
<ul> |
|
11386 |
<li><eventlink id="VMStart"></eventlink></li> |
|
11387 |
<li><eventlink id="VMInit"></eventlink></li> |
|
11388 |
<li><eventlink id="VMDeath"></eventlink></li> |
|
11389 |
<li><eventlink id="ThreadStart"></eventlink></li> |
|
11390 |
<li><eventlink id="ThreadEnd"></eventlink></li> |
|
11391 |
<li><eventlink id="ClassLoad"></eventlink></li> |
|
11392 |
<li><eventlink id="ClassPrepare"></eventlink></li> |
|
11393 |
</ul> |
|
11394 |
</intro> |
|
11395 |
||
11396 |
<intro label="Event Callbacks" id="jvmtiEventCallbacks"> |
|
11397 |
The event callback structure below is used to specify the handler function |
|
11398 |
for events. It is set with the |
|
11399 |
<functionlink id="SetEventCallbacks"></functionlink> function. |
|
11400 |
</intro> |
|
11401 |
||
11402 |
<event label="Single Step" |
|
11403 |
id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60"> |
|
11404 |
<description> |
|
11405 |
Single step events allow the agent to trace thread execution |
|
11406 |
at the finest granularity allowed by the VM. A single step event is |
|
11407 |
generated whenever a thread reaches a new location. |
|
11408 |
Typically, single step events represent the completion of one VM |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
11409 |
instruction as defined in <vmspec/>. However, some implementations |
1 | 11410 |
may define locations differently. In any case the |
11411 |
<code>method</code> and <code>location</code> |
|
11412 |
parameters uniquely identify the current location and allow |
|
11413 |
the mapping to source file and line number when that information is |
|
11414 |
available. |
|
11415 |
<p/> |
|
11416 |
No single step events are generated from within native methods. |
|
11417 |
</description> |
|
11418 |
<origin>jvmdi</origin> |
|
11419 |
<capabilities> |
|
11420 |
<required id="can_generate_single_step_events"></required> |
|
11421 |
</capabilities> |
|
11422 |
<parameters> |
|
11423 |
<param id="jni_env"> |
|
11424 |
<outptr> |
|
11425 |
<struct>JNIEnv</struct> |
|
11426 |
</outptr> |
|
11427 |
<description> |
|
11428 |
The JNI environment of the event (current) thread |
|
11429 |
</description> |
|
11430 |
</param> |
|
11431 |
<param id="thread"> |
|
11432 |
<jthread/> |
|
11433 |
<description> |
|
11434 |
Thread about to execution a new instruction |
|
11435 |
</description> |
|
11436 |
</param> |
|
11437 |
<param id="klass"> |
|
11438 |
<jclass method="method"/> |
|
11439 |
<description> |
|
11440 |
Class of the method about to execute a new instruction |
|
11441 |
</description> |
|
11442 |
</param> |
|
11443 |
<param id="method"> |
|
11444 |
<jmethodID class="klass"/> |
|
11445 |
<description> |
|
11446 |
Method about to execute a new instruction |
|
11447 |
</description> |
|
11448 |
</param> |
|
11449 |
<param id="location"> |
|
11450 |
<jlocation/> |
|
11451 |
<description> |
|
11452 |
Location of the new instruction |
|
11453 |
</description> |
|
11454 |
</param> |
|
11455 |
</parameters> |
|
11456 |
</event> |
|
11457 |
||
11458 |
<event label="Breakpoint" |
|
11459 |
id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62"> |
|
11460 |
<description> |
|
11461 |
Breakpoint events are generated whenever a thread reaches a location |
|
11462 |
designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>. |
|
11463 |
The <code>method</code> and <code>location</code> |
|
11464 |
parameters uniquely identify the current location and allow |
|
11465 |
the mapping to source file and line number when that information is |
|
11466 |
available. |
|
11467 |
</description> |
|
11468 |
<origin>jvmdi</origin> |
|
11469 |
<capabilities> |
|
11470 |
<required id="can_generate_breakpoint_events"></required> |
|
11471 |
</capabilities> |
|
11472 |
<parameters> |
|
11473 |
<param id="jni_env"> |
|
11474 |
<outptr> |
|
11475 |
<struct>JNIEnv</struct> |
|
11476 |
</outptr> |
|
11477 |
<description> |
|
11478 |
The JNI environment of the event (current) thread. |
|
11479 |
</description> |
|
11480 |
</param> |
|
11481 |
<param id="thread"> |
|
11482 |
<jthread/> |
|
11483 |
<description> |
|
11484 |
Thread that hit the breakpoint |
|
11485 |
</description> |
|
11486 |
</param> |
|
11487 |
<param id="klass"> |
|
11488 |
<jclass method="method"/> |
|
11489 |
<description> |
|
11490 |
Class of the method that hit the breakpoint |
|
11491 |
</description> |
|
11492 |
</param> |
|
11493 |
<param id="method"> |
|
11494 |
<jmethodID class="klass"/> |
|
11495 |
<description> |
|
11496 |
Method that hit the breakpoint |
|
11497 |
</description> |
|
11498 |
</param> |
|
11499 |
<param id="location"> |
|
11500 |
<jlocation/> |
|
11501 |
<description> |
|
11502 |
location of the breakpoint |
|
11503 |
</description> |
|
11504 |
</param> |
|
11505 |
</parameters> |
|
11506 |
</event> |
|
11507 |
||
11508 |
<event label="Field Access" |
|
11509 |
id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63"> |
|
11510 |
<description> |
|
11511 |
Field access events are generated whenever a thread accesses |
|
11512 |
a field that was designated as a watchpoint |
|
11513 |
with <functionlink id="SetFieldAccessWatch"></functionlink>. |
|
11514 |
The <code>method</code> and <code>location</code> |
|
11515 |
parameters uniquely identify the current location and allow |
|
11516 |
the mapping to source file and line number when that information is |
|
11517 |
available. |
|
11518 |
</description> |
|
11519 |
<origin>jvmdi</origin> |
|
11520 |
<capabilities> |
|
11521 |
<required id="can_generate_field_access_events"></required> |
|
11522 |
</capabilities> |
|
11523 |
<parameters> |
|
11524 |
<param id="jni_env"> |
|
11525 |
<outptr> |
|
11526 |
<struct>JNIEnv</struct> |
|
11527 |
</outptr> |
|
11528 |
<description> |
|
11529 |
The JNI environment of the event (current) thread |
|
11530 |
</description> |
|
11531 |
</param> |
|
11532 |
<param id="thread"> |
|
11533 |
<jthread/> |
|
11534 |
<description> |
|
11535 |
Thread accessing the field |
|
11536 |
</description> |
|
11537 |
</param> |
|
11538 |
<param id="klass"> |
|
11539 |
<jclass method="method"/> |
|
11540 |
<description> |
|
11541 |
Class of the method where the access is occurring |
|
11542 |
</description> |
|
11543 |
</param> |
|
11544 |
<param id="method"> |
|
11545 |
<jmethodID class="klass"/> |
|
11546 |
<description> |
|
11547 |
Method where the access is occurring |
|
11548 |
</description> |
|
11549 |
</param> |
|
11550 |
<param id="location"> |
|
11551 |
<jlocation/> |
|
11552 |
<description> |
|
11553 |
Location where the access is occurring |
|
11554 |
</description> |
|
11555 |
</param> |
|
11556 |
<param id="field_klass"> |
|
11557 |
<jclass field="field"/> |
|
11558 |
<description> |
|
11559 |
Class of the field being accessed |
|
11560 |
</description> |
|
11561 |
</param> |
|
11562 |
<param id="object"> |
|
11563 |
<jobject/> |
|
11564 |
<description> |
|
11565 |
Object with the field being accessed if the field is an |
|
11566 |
instance field; <code>NULL</code> otherwise |
|
11567 |
</description> |
|
11568 |
</param> |
|
11569 |
<param id="field"> |
|
11570 |
<jfieldID class="field_klass"/> |
|
11571 |
<description> |
|
11572 |
Field being accessed |
|
11573 |
</description> |
|
11574 |
</param> |
|
11575 |
</parameters> |
|
11576 |
</event> |
|
11577 |
||
11578 |
<event label="Field Modification" |
|
11579 |
id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64"> |
|
11580 |
<description> |
|
11581 |
Field modification events are generated whenever a thread modifies |
|
11582 |
a field that was designated as a watchpoint |
|
11583 |
with <functionlink id="SetFieldModificationWatch"></functionlink>. |
|
11584 |
The <code>method</code> and <code>location</code> |
|
11585 |
parameters uniquely identify the current location and allow |
|
11586 |
the mapping to source file and line number when that information is |
|
11587 |
available. |
|
11588 |
</description> |
|
11589 |
<origin>jvmdi</origin> |
|
11590 |
<capabilities> |
|
11591 |
<required id="can_generate_field_modification_events"></required> |
|
11592 |
</capabilities> |
|
11593 |
<parameters> |
|
11594 |
<param id="jni_env"> |
|
11595 |
<outptr> |
|
11596 |
<struct>JNIEnv</struct> |
|
11597 |
</outptr> |
|
11598 |
<description> |
|
11599 |
The JNI environment of the event (current) thread |
|
11600 |
</description> |
|
11601 |
</param> |
|
11602 |
<param id="thread"> |
|
11603 |
<jthread/> |
|
11604 |
<description> |
|
11605 |
Thread modifying the field |
|
11606 |
</description> |
|
11607 |
</param> |
|
11608 |
<param id="klass"> |
|
11609 |
<jclass method="method"/> |
|
11610 |
<description> |
|
11611 |
Class of the method where the modification is occurring |
|
11612 |
</description> |
|
11613 |
</param> |
|
11614 |
<param id="method"> |
|
11615 |
<jmethodID class="klass"/> |
|
11616 |
<description> |
|
11617 |
Method where the modification is occurring |
|
11618 |
</description> |
|
11619 |
</param> |
|
11620 |
<param id="location"> |
|
11621 |
<jlocation/> |
|
11622 |
<description> |
|
11623 |
Location where the modification is occurring |
|
11624 |
</description> |
|
11625 |
</param> |
|
11626 |
<param id="field_klass"> |
|
11627 |
<jclass field="field"/> |
|
11628 |
<description> |
|
11629 |
Class of the field being modified |
|
11630 |
</description> |
|
11631 |
</param> |
|
11632 |
<param id="object"> |
|
11633 |
<jobject/> |
|
11634 |
<description> |
|
11635 |
Object with the field being modified if the field is an |
|
11636 |
instance field; <code>NULL</code> otherwise |
|
11637 |
</description> |
|
11638 |
</param> |
|
11639 |
<param id="field"> |
|
11640 |
<jfieldID class="field_klass"/> |
|
11641 |
<description> |
|
11642 |
Field being modified |
|
11643 |
</description> |
|
11644 |
</param> |
|
11645 |
<param id="signature_type"> |
|
11646 |
<char/> |
|
11647 |
<description> |
|
11648 |
Signature type of the new value |
|
11649 |
</description> |
|
11650 |
</param> |
|
11651 |
<param id="new_value"> |
|
11652 |
<jvalue/> |
|
11653 |
<description> |
|
11654 |
The new value |
|
11655 |
</description> |
|
11656 |
</param> |
|
11657 |
</parameters> |
|
11658 |
</event> |
|
11659 |
||
11660 |
<event label="Frame Pop" |
|
11661 |
id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61"> |
|
11662 |
<description> |
|
11663 |
Frame pop events are generated upon exit from a single method |
|
11664 |
in a single frame as specified |
|
11665 |
in a call to <functionlink id="NotifyFramePop"></functionlink>. |
|
11666 |
This is true whether termination is caused by |
|
11667 |
executing its return instruction |
|
11668 |
or by throwing an exception to its caller |
|
11669 |
(see <paramlink id="was_popped_by_exception"></paramlink>). |
|
11670 |
However, frame pops caused by the <functionlink id="PopFrame"/> |
|
11671 |
function are not reported. |
|
11672 |
<p/> |
|
11673 |
The location reported by <functionlink id="GetFrameLocation"></functionlink> |
|
11674 |
identifies the executable location in the returning method, |
|
11675 |
immediately prior to the return. |
|
11676 |
</description> |
|
11677 |
<origin>jvmdi</origin> |
|
11678 |
<capabilities> |
|
11679 |
<required id="can_generate_frame_pop_events"></required> |
|
11680 |
</capabilities> |
|
11681 |
<parameters> |
|
11682 |
<param id="jni_env"> |
|
11683 |
<outptr> |
|
11684 |
<struct>JNIEnv</struct> |
|
11685 |
</outptr> |
|
11686 |
<description> |
|
11687 |
The JNI environment of the event (current) thread |
|
11688 |
</description> |
|
11689 |
</param> |
|
11690 |
<param id="thread"> |
|
11691 |
<jthread/> |
|
11692 |
<description> |
|
11693 |
Thread that is popping the frame |
|
11694 |
</description> |
|
11695 |
</param> |
|
11696 |
<param id="klass"> |
|
11697 |
<jclass method="method"/> |
|
11698 |
<description> |
|
11699 |
Class of the method being popped |
|
11700 |
</description> |
|
11701 |
</param> |
|
11702 |
<param id="method"> |
|
11703 |
<jmethodID class="klass"/> |
|
11704 |
<description> |
|
11705 |
Method being popped |
|
11706 |
</description> |
|
11707 |
</param> |
|
11708 |
<param id="was_popped_by_exception"> |
|
11709 |
<jboolean/> |
|
11710 |
<description> |
|
11711 |
True if frame was popped by a thrown exception. |
|
11712 |
False if method exited through its return instruction. |
|
11713 |
</description> |
|
11714 |
</param> |
|
11715 |
</parameters> |
|
11716 |
</event> |
|
11717 |
||
11718 |
<event label="Method Entry" |
|
11719 |
id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65"> |
|
11720 |
<description> |
|
11721 |
Method entry events are generated upon entry of Java |
|
11722 |
programming language methods (including native methods). |
|
11723 |
<p/> |
|
11724 |
The location reported by <functionlink id="GetFrameLocation"></functionlink> |
|
11725 |
identifies the initial executable location in |
|
11726 |
the method. |
|
11727 |
<p/> |
|
11728 |
Enabling method |
|
11729 |
entry or exit events will significantly degrade performance on many platforms and is thus |
|
11730 |
not advised for performance critical usage (such as profiling). |
|
11731 |
<internallink id="bci">Bytecode instrumentation</internallink> should be |
|
11732 |
used in these cases. |
|
11733 |
</description> |
|
11734 |
<origin>jvmdi</origin> |
|
11735 |
<capabilities> |
|
11736 |
<required id="can_generate_method_entry_events"></required> |
|
11737 |
</capabilities> |
|
11738 |
<parameters> |
|
11739 |
<param id="jni_env"> |
|
11740 |
<outptr> |
|
11741 |
<struct>JNIEnv</struct> |
|
11742 |
</outptr> |
|
11743 |
<description> |
|
11744 |
The JNI environment of the event (current) thread |
|
11745 |
</description> |
|
11746 |
</param> |
|
11747 |
<param id="thread"> |
|
11748 |
<jthread/> |
|
11749 |
<description> |
|
11750 |
Thread entering the method |
|
11751 |
</description> |
|
11752 |
</param> |
|
11753 |
<param id="klass"> |
|
11754 |
<jclass method="method"/> |
|
11755 |
<description> |
|
11756 |
Class of the method being entered |
|
11757 |
</description> |
|
11758 |
</param> |
|
11759 |
<param id="method"> |
|
11760 |
<jmethodID class="klass"/> |
|
11761 |
<description> |
|
11762 |
Method being entered |
|
11763 |
</description> |
|
11764 |
</param> |
|
11765 |
</parameters> |
|
11766 |
</event> |
|
11767 |
||
11768 |
<event label="Method Exit" |
|
11769 |
id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66"> |
|
11770 |
<description> |
|
11771 |
Method exit events are generated upon exit from Java |
|
11772 |
programming language methods (including native methods). |
|
11773 |
This is true whether termination is caused by |
|
11774 |
executing its return instruction |
|
11775 |
or by throwing an exception to its caller |
|
11776 |
(see <paramlink id="was_popped_by_exception"></paramlink>). |
|
11777 |
<p/> |
|
11778 |
The <code>method</code> field uniquely identifies the |
|
11779 |
method being entered or exited. The <code>frame</code> field provides |
|
11780 |
access to the stack frame for the method. |
|
11781 |
<p/> |
|
11782 |
The location reported by <functionlink id="GetFrameLocation"></functionlink> |
|
11783 |
identifies the executable location in the returning method |
|
11784 |
immediately prior to the return. |
|
11785 |
<p/> |
|
11786 |
Enabling method |
|
11787 |
entry or exit events will significantly degrade performance on many platforms and is thus |
|
11788 |
not advised for performance critical usage (such as profiling). |
|
11789 |
<internallink id="bci">Bytecode instrumentation</internallink> should be |
|
11790 |
used in these cases. |
|
11791 |
</description> |
|
11792 |
<origin>jvmdi</origin> |
|
11793 |
<capabilities> |
|
11794 |
<required id="can_generate_method_exit_events"></required> |
|
11795 |
</capabilities> |
|
11796 |
<parameters> |
|
11797 |
<param id="jni_env"> |
|
11798 |
<outptr> |
|
11799 |
<struct>JNIEnv</struct> |
|
11800 |
</outptr> |
|
11801 |
<description> |
|
11802 |
The JNI environment of the event (current) thread |
|
11803 |
</description> |
|
11804 |
</param> |
|
11805 |
<param id="thread"> |
|
11806 |
<jthread/> |
|
11807 |
<description> |
|
11808 |
Thread exiting the method |
|
11809 |
</description> |
|
11810 |
</param> |
|
11811 |
<param id="klass"> |
|
11812 |
<jclass method="method"/> |
|
11813 |
<description> |
|
11814 |
Class of the method being exited |
|
11815 |
</description> |
|
11816 |
</param> |
|
11817 |
<param id="method"> |
|
11818 |
<jmethodID class="klass"/> |
|
11819 |
<description> |
|
11820 |
Method being exited |
|
11821 |
</description> |
|
11822 |
</param> |
|
11823 |
<param id="was_popped_by_exception"> |
|
11824 |
<jboolean/> |
|
11825 |
<description> |
|
11826 |
True if frame was popped by a thrown exception. |
|
11827 |
False if method exited through its return instruction. |
|
11828 |
</description> |
|
11829 |
</param> |
|
11830 |
<param id="return_value"> |
|
11831 |
<jvalue/> |
|
11832 |
<description> |
|
11833 |
The return value of the method being exited. |
|
11834 |
Undefined and should not be used if |
|
11835 |
<paramlink id="was_popped_by_exception"></paramlink> |
|
11836 |
is true. |
|
11837 |
</description> |
|
11838 |
</param> |
|
11839 |
</parameters> |
|
11840 |
</event> |
|
11841 |
||
11842 |
<event label="Native Method Bind" phase="any" |
|
11843 |
id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67"> |
|
11844 |
<description> |
|
11845 |
A Native Method Bind event is sent when a VM binds a |
|
11846 |
Java programming language native method |
|
11847 |
to the address of a function that implements the native method. |
|
11848 |
This will occur when the native method is called for the first time |
|
11849 |
and also occurs when the JNI function <code>RegisterNatives</code> is called. |
|
11850 |
This event allows the bind to be redirected to an agent-specified |
|
11851 |
proxy function. |
|
11852 |
This event is not sent when the native method is unbound. |
|
11853 |
Typically, this proxy function will need to be specific to a |
|
11854 |
particular method or, to handle the general case, automatically |
|
11855 |
generated assembly code, since after instrumentation code is |
|
11856 |
executed the function at the original binding |
|
11857 |
address will usually be invoked. |
|
11858 |
The original binding can be restored or the redirection changed |
|
11859 |
by use of the JNI function <code>RegisterNatives</code>. |
|
11860 |
Some events may be sent during the primordial phase, JNI and |
|
11861 |
most of <jvmti/> cannot be used at this time but the method and |
|
11862 |
address can be saved for use later. |
|
11863 |
</description> |
|
11864 |
<origin>new</origin> |
|
11865 |
<capabilities> |
|
11866 |
<required id="can_generate_native_method_bind_events"></required> |
|
11867 |
</capabilities> |
|
11868 |
<parameters> |
|
11869 |
<param id="jni_env"> |
|
11870 |
<outptr> |
|
11871 |
<struct>JNIEnv</struct> |
|
11872 |
</outptr> |
|
11873 |
<description> |
|
11874 |
The JNI environment of the event (current) thread |
|
11875 |
Will be <code>NULL</code> if sent during the primordial |
|
11876 |
<functionlink id="GetPhase">phase</functionlink>. |
|
11877 |
</description> |
|
11878 |
</param> |
|
11879 |
<param id="thread"> |
|
11880 |
<jthread/> |
|
11881 |
<description> |
|
11882 |
Thread requesting the bind |
|
11883 |
</description> |
|
11884 |
</param> |
|
11885 |
<param id="klass"> |
|
11886 |
<jclass method="method"/> |
|
11887 |
<description> |
|
11888 |
Class of the method being bound |
|
11889 |
</description> |
|
11890 |
</param> |
|
11891 |
<param id="method"> |
|
11892 |
<jmethodID class="klass"/> |
|
11893 |
<description> |
|
11894 |
Native method being bound |
|
11895 |
</description> |
|
11896 |
</param> |
|
11897 |
<param id="address"> |
|
11898 |
<outptr><void/></outptr> |
|
11899 |
<description> |
|
11900 |
The address the VM is about to bind to--that is, the |
|
11901 |
address of the implementation of the native method |
|
11902 |
</description> |
|
11903 |
</param> |
|
11904 |
<param id="new_address_ptr"> |
|
11905 |
<agentbuf><void/></agentbuf> |
|
11906 |
<description> |
|
11907 |
if the referenced address is changed (that is, if |
|
11908 |
<code>*new_address_ptr</code> is set), the binding |
|
11909 |
will instead be made to the supplied address. |
|
11910 |
</description> |
|
11911 |
</param> |
|
11912 |
</parameters> |
|
11913 |
</event> |
|
11914 |
||
11915 |
<event label="Exception" |
|
11916 |
id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58"> |
|
11917 |
<description> |
|
11918 |
Exception events are generated whenever an exception is first detected |
|
11919 |
in a Java programming language method. |
|
11920 |
Where "exception" means any <code>java.lang.Throwable</code>. |
|
11921 |
The exception may have been thrown by a Java programming language or native |
|
11922 |
method, but in the case of native methods, the event is not generated |
|
11923 |
until the exception is first seen by a Java programming language method. If an exception is |
|
11924 |
set and cleared in a native method (and thus is never visible to Java programming language code), |
|
11925 |
no exception event is generated. |
|
11926 |
<p/> |
|
11927 |
The <code>method</code> and <code>location</code> |
|
11928 |
parameters uniquely identify the current location |
|
11929 |
(where the exception was detected) and allow |
|
11930 |
the mapping to source file and line number when that information is |
|
11931 |
available. The <code>exception</code> field identifies the thrown |
|
11932 |
exception object. The <code>catch_method</code> |
|
11933 |
and <code>catch_location</code> identify the location of the catch clause, |
|
11934 |
if any, that handles the thrown exception. If there is no such catch clause, |
|
11935 |
each field is set to 0. There is no guarantee that the thread will ever |
|
11936 |
reach this catch clause. If there are native methods on the call stack |
|
11937 |
between the throw location and the catch clause, the exception may |
|
11938 |
be reset by one of those native methods. |
|
11939 |
Similarly, exceptions that are reported as uncaught (<code>catch_klass</code> |
|
11940 |
et al. set to 0) may in fact be caught by native code. |
|
11941 |
Agents can check for these occurrences by monitoring |
|
11942 |
<eventlink id="ExceptionCatch"></eventlink> events. |
|
11943 |
Note that finally clauses are implemented as catch and re-throw. Therefore they |
|
11944 |
will be reported in the catch location. |
|
11945 |
</description> |
|
11946 |
<origin>jvmdi</origin> |
|
11947 |
<capabilities> |
|
11948 |
<required id="can_generate_exception_events"></required> |
|
11949 |
</capabilities> |
|
11950 |
<parameters> |
|
11951 |
<param id="jni_env"> |
|
11952 |
<outptr> |
|
11953 |
<struct>JNIEnv</struct> |
|
11954 |
</outptr> |
|
11955 |
<description> |
|
11956 |
The JNI environment of the event (current) thread |
|
11957 |
</description> |
|
11958 |
</param> |
|
11959 |
<param id="thread"> |
|
11960 |
<jthread/> |
|
11961 |
<description> |
|
11962 |
Thread generating the exception |
|
11963 |
</description> |
|
11964 |
</param> |
|
11965 |
<param id="klass"> |
|
11966 |
<jclass method="method"/> |
|
11967 |
<description> |
|
11968 |
Class generating the exception |
|
11969 |
</description> |
|
11970 |
</param> |
|
11971 |
<param id="method"> |
|
11972 |
<jmethodID class="klass"/> |
|
11973 |
<description> |
|
11974 |
Method generating the exception |
|
11975 |
</description> |
|
11976 |
</param> |
|
11977 |
<param id="location"> |
|
11978 |
<jlocation/> |
|
11979 |
<description> |
|
11980 |
Location where exception occurred |
|
11981 |
</description> |
|
11982 |
</param> |
|
11983 |
<param id="exception"> |
|
11984 |
<jobject/> |
|
11985 |
<description> |
|
11986 |
The exception being thrown |
|
11987 |
</description> |
|
11988 |
</param> |
|
11989 |
<param id="catch_klass"> |
|
11990 |
<jclass method="catch_method"/> |
|
11991 |
<description> |
|
11992 |
Class that will catch the exception, or <code>NULL</code> if no known catch |
|
11993 |
</description> |
|
11994 |
</param> |
|
11995 |
<param id="catch_method"> |
|
11996 |
<jmethodID class="catch_klass"/> |
|
11997 |
<description> |
|
11998 |
Method that will catch the exception, or <code>NULL</code> if no known catch |
|
11999 |
</description> |
|
12000 |
</param> |
|
12001 |
<param id="catch_location"> |
|
12002 |
<jlocation/> |
|
12003 |
<description> |
|
12004 |
location which will catch the exception or zero if no known catch |
|
12005 |
</description> |
|
12006 |
</param> |
|
12007 |
</parameters> |
|
12008 |
</event> |
|
12009 |
||
12010 |
<event label="Exception Catch" |
|
12011 |
id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59"> |
|
12012 |
<description> |
|
12013 |
Exception catch events are generated whenever a thrown exception is caught. |
|
12014 |
Where "exception" means any <code>java.lang.Throwable</code>. |
|
12015 |
If the exception is caught in a Java programming language method, the event is generated |
|
12016 |
when the catch clause is reached. If the exception is caught in a native |
|
12017 |
method, the event is generated as soon as control is returned to a Java programming language |
|
12018 |
method. Exception catch events are generated for any exception for which |
|
12019 |
a throw was detected in a Java programming language method. |
|
12020 |
Note that finally clauses are implemented as catch and re-throw. Therefore they |
|
12021 |
will generate exception catch events. |
|
12022 |
<p/> |
|
12023 |
The <code>method</code> and <code>location</code> |
|
12024 |
parameters uniquely identify the current location |
|
12025 |
and allow the mapping to source file and line number when that information is |
|
12026 |
available. For exceptions caught in a Java programming language method, the |
|
12027 |
<code>exception</code> object identifies the exception object. Exceptions |
|
12028 |
caught in native methods are not necessarily available by the time the |
|
12029 |
exception catch is reported, so the <code>exception</code> field is set |
|
12030 |
to <code>NULL</code>. |
|
12031 |
</description> |
|
12032 |
<origin>jvmdi</origin> |
|
12033 |
<capabilities> |
|
12034 |
<required id="can_generate_exception_events"></required> |
|
12035 |
</capabilities> |
|
12036 |
<parameters> |
|
12037 |
<param id="jni_env"> |
|
12038 |
<outptr> |
|
12039 |
<struct>JNIEnv</struct> |
|
12040 |
</outptr> |
|
12041 |
<description> |
|
12042 |
The JNI environment of the event (current) thread |
|
12043 |
</description> |
|
12044 |
</param> |
|
12045 |
<param id="thread"> |
|
12046 |
<jthread/> |
|
12047 |
<description> |
|
12048 |
Thread catching the exception |
|
12049 |
</description> |
|
12050 |
</param> |
|
12051 |
<param id="klass"> |
|
12052 |
<jclass method="method"/> |
|
12053 |
<description> |
|
12054 |
Class catching the exception |
|
12055 |
</description> |
|
12056 |
</param> |
|
12057 |
<param id="method"> |
|
12058 |
<jmethodID class="klass"/> |
|
12059 |
<description> |
|
12060 |
Method catching the exception |
|
12061 |
</description> |
|
12062 |
</param> |
|
12063 |
<param id="location"> |
|
12064 |
<jlocation/> |
|
12065 |
<description> |
|
12066 |
Location where exception is being caught |
|
12067 |
</description> |
|
12068 |
</param> |
|
12069 |
<param id="exception"> |
|
12070 |
<jobject/> |
|
12071 |
<description> |
|
12072 |
Exception being caught |
|
12073 |
</description> |
|
12074 |
</param> |
|
12075 |
</parameters> |
|
12076 |
</event> |
|
12077 |
||
12078 |
<event label="Thread Start" |
|
12079 |
id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start"> |
|
12080 |
<description> |
|
12081 |
Thread start events are generated by a new thread before its initial |
|
12082 |
method executes. |
|
12083 |
<p/> |
|
12084 |
A thread may be listed in the array returned by |
|
12085 |
<functionlink id="GetAllThreads"></functionlink> |
|
12086 |
before its thread start event is generated. |
|
12087 |
It is possible for other events to be generated |
|
12088 |
on a thread before its thread start event. |
|
12089 |
<p/> |
|
12090 |
The event is sent on the newly started <paramlink id="thread"></paramlink>. |
|
12091 |
</description> |
|
12092 |
<origin>jvmdi</origin> |
|
12093 |
<capabilities> |
|
12094 |
</capabilities> |
|
12095 |
<parameters> |
|
12096 |
<param id="jni_env"> |
|
12097 |
<outptr> |
|
12098 |
<struct>JNIEnv</struct> |
|
12099 |
</outptr> |
|
12100 |
<description> |
|
12101 |
The JNI environment of the event (current) thread. |
|
12102 |
</description> |
|
12103 |
</param> |
|
12104 |
<param id="thread"> |
|
12105 |
<jthread/> |
|
12106 |
<description> |
|
12107 |
Thread starting |
|
12108 |
</description> |
|
12109 |
</param> |
|
12110 |
</parameters> |
|
12111 |
</event> |
|
12112 |
||
12113 |
<event label="Thread End" |
|
12114 |
id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> |
|
12115 |
<description> |
|
12116 |
Thread end events are generated by a terminating thread |
|
12117 |
after its initial method has finished execution. |
|
12118 |
<p/> |
|
12119 |
A thread may be listed in the array returned by |
|
12120 |
<functionlink id="GetAllThreads"></functionlink> |
|
12121 |
after its thread end event is generated. |
|
12122 |
No events are generated on a thread |
|
12123 |
after its thread end event. |
|
12124 |
<p/> |
|
12125 |
The event is sent on the dying <paramlink id="thread"></paramlink>. |
|
12126 |
</description> |
|
12127 |
<origin>jvmdi</origin> |
|
12128 |
<capabilities> |
|
12129 |
</capabilities> |
|
12130 |
<parameters> |
|
12131 |
<param id="jni_env"> |
|
12132 |
<outptr> |
|
12133 |
<struct>JNIEnv</struct> |
|
12134 |
</outptr> |
|
12135 |
<description> |
|
12136 |
The JNI environment of the event (current) thread. |
|
12137 |
</description> |
|
12138 |
</param> |
|
12139 |
<param id="thread"> |
|
12140 |
<jthread/> |
|
12141 |
<description> |
|
12142 |
Thread ending |
|
12143 |
</description> |
|
12144 |
</param> |
|
12145 |
</parameters> |
|
12146 |
</event> |
|
12147 |
||
12148 |
<event label="Class Load" |
|
12149 |
id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55"> |
|
12150 |
<description> |
|
12151 |
A class load event is generated when a class is first loaded. The order |
|
12152 |
of class load events generated by a particular thread are guaranteed |
|
12153 |
to match the order of class loading within that thread. |
|
12154 |
Array class creation does not generate a class load event. |
|
12155 |
The creation of a primitive class (for example, java.lang.Integer.TYPE) |
|
12156 |
does not generate a class load event. |
|
12157 |
<p/> |
|
12158 |
This event is sent at an early stage in loading the class. As |
|
12159 |
a result the class should be used carefully. Note, for example, |
|
12160 |
that methods and fields are not yet loaded, so queries for methods, |
|
12161 |
fields, subclasses, and so on will not give correct results. |
|
12162 |
See "Loading of Classes and Interfaces" in the <i>Java Language |
|
12163 |
Specification</i>. For most |
|
12164 |
purposes the <eventlink id="ClassPrepare"></eventlink> event will |
|
12165 |
be more useful. |
|
12166 |
</description> |
|
12167 |
<origin>jvmdi</origin> |
|
12168 |
<capabilities> |
|
12169 |
</capabilities> |
|
12170 |
<parameters> |
|
12171 |
<param id="jni_env"> |
|
12172 |
<outptr> |
|
12173 |
<struct>JNIEnv</struct> |
|
12174 |
</outptr> |
|
12175 |
<description> |
|
12176 |
The JNI environment of the event (current) thread |
|
12177 |
</description> |
|
12178 |
</param> |
|
12179 |
<param id="thread"> |
|
12180 |
<jthread/> |
|
12181 |
<description> |
|
12182 |
Thread loading the class |
|
12183 |
</description> |
|
12184 |
</param> |
|
12185 |
<param id="klass"> |
|
12186 |
<jclass/> |
|
12187 |
<description> |
|
12188 |
Class being loaded |
|
12189 |
</description> |
|
12190 |
</param> |
|
12191 |
</parameters> |
|
12192 |
</event> |
|
12193 |
||
12194 |
<elide> |
|
12195 |
<event label="Class Unload" |
|
12196 |
id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57"> |
|
12197 |
<description> |
|
12198 |
A class unload event is generated when the class is about to be unloaded. |
|
12199 |
Class unload events take place during garbage collection and must be |
|
12200 |
handled extremely carefully. The garbage collector holds many locks |
|
12201 |
and has suspended all other threads, so the event handler cannot depend |
|
12202 |
on the ability to acquire any locks. The class unload event handler should |
|
12203 |
do as little as possible, perhaps by queuing information to be processed |
|
12204 |
later. In particular, the <code>jclass</code> should be used only in |
|
12205 |
the JNI function <code>isSameObject</code> or in the following <jvmti/> functions: |
|
12206 |
<ul> |
|
12207 |
<li><functionlink id="GetClassSignature"></functionlink></li> |
|
12208 |
<li><functionlink id="GetSourceFileName"></functionlink></li> |
|
12209 |
<li><functionlink id="IsInterface"></functionlink></li> |
|
12210 |
<li><functionlink id="IsArrayClass"></functionlink></li> |
|
12211 |
</ul> |
|
12212 |
</description> |
|
12213 |
<origin>jvmdi</origin> |
|
12214 |
<capabilities> |
|
12215 |
</capabilities> |
|
12216 |
<parameters> |
|
12217 |
<param id="jni_env"> |
|
12218 |
<outptr> |
|
12219 |
<struct>JNIEnv</struct> |
|
12220 |
</outptr> |
|
12221 |
<description> |
|
12222 |
The JNI environment of the event (current) thread |
|
12223 |
</description> |
|
12224 |
</param> |
|
12225 |
<param id="thread"> |
|
12226 |
<jthread/> |
|
12227 |
<description> |
|
12228 |
Thread generating the class unload |
|
12229 |
</description> |
|
12230 |
</param> |
|
12231 |
<param id="klass"> |
|
12232 |
<jclass/> |
|
12233 |
<description> |
|
12234 |
Class being unloaded |
|
12235 |
</description> |
|
12236 |
</param> |
|
12237 |
</parameters> |
|
12238 |
</event> |
|
12239 |
</elide> |
|
12240 |
||
12241 |
<event label="Class Prepare" |
|
12242 |
id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56"> |
|
12243 |
<description> |
|
12244 |
A class prepare event is generated when class preparation is complete. |
|
12245 |
At this point, class fields, methods, and implemented interfaces are |
|
12246 |
available, and no code from the class has been executed. Since array |
|
12247 |
classes never have fields or methods, class prepare events are not |
|
12248 |
generated for them. Class prepare events are not generated for |
|
12249 |
primitive classes (for example, <code>java.lang.Integer.TYPE</code>). |
|
12250 |
</description> |
|
12251 |
<origin>jvmdi</origin> |
|
12252 |
<capabilities> |
|
12253 |
</capabilities> |
|
12254 |
<parameters> |
|
12255 |
<param id="jni_env"> |
|
12256 |
<outptr> |
|
12257 |
<struct>JNIEnv</struct> |
|
12258 |
</outptr> |
|
12259 |
<description> |
|
12260 |
The JNI environment of the event (current) thread |
|
12261 |
</description> |
|
12262 |
</param> |
|
12263 |
<param id="thread"> |
|
12264 |
<jthread/> |
|
12265 |
<description> |
|
12266 |
Thread generating the class prepare |
|
12267 |
</description> |
|
12268 |
</param> |
|
12269 |
<param id="klass"> |
|
12270 |
<jclass/> |
|
12271 |
<description> |
|
12272 |
Class being prepared |
|
12273 |
</description> |
|
12274 |
</param> |
|
12275 |
</parameters> |
|
12276 |
</event> |
|
12277 |
||
12278 |
<event label="Class File Load Hook" phase="any" |
|
12279 |
id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54"> |
|
12280 |
<description> |
|
12281 |
This event is sent when the VM obtains class file data, |
|
12282 |
but before it constructs |
|
12283 |
the in-memory representation for that class. |
|
12284 |
This event is also sent when the class is being modified by the |
|
12285 |
<functionlink id="RetransformClasses"/> function or |
|
12286 |
the <functionlink id="RedefineClasses"/> function, |
|
12287 |
called in any <jvmti/> environment. |
|
12288 |
The agent can instrument |
|
12289 |
the existing class file data sent by the VM to include profiling/debugging hooks. |
|
12290 |
See the description of |
|
12291 |
<internallink id="bci">bytecode instrumentation</internallink> |
|
12292 |
for usage information. |
|
12293 |
<p/> |
|
12294 |
This event may be sent before the VM is initialized (the primordial |
|
12295 |
<functionlink id="GetPhase">phase</functionlink>). During this time |
|
12296 |
no VM resources should be created. Some classes might not be compatible |
|
12297 |
with the function (eg. ROMized classes) and this event will not be |
|
12298 |
generated for these classes. |
|
12299 |
<p/> |
|
12300 |
The agent must allocate the space for the modified |
|
12301 |
class file data buffer |
|
12302 |
using the memory allocation function |
|
12303 |
<functionlink id="Allocate"></functionlink> because the |
|
12304 |
VM is responsible for freeing the new class file data buffer |
|
12305 |
using <functionlink id="Deallocate"></functionlink>. |
|
12306 |
Note that <functionlink id="Allocate"></functionlink> |
|
12307 |
is permitted during the primordial phase. |
|
12308 |
<p/> |
|
12309 |
If the agent wishes to modify the class file, it must set |
|
12310 |
<code>new_class_data</code> to point |
|
12311 |
to the newly instrumented class file data buffer and set |
|
12312 |
<code>new_class_data_len</code> to the length of that |
|
12313 |
buffer before returning |
|
12314 |
from this call. If no modification is desired, the agent simply |
|
12315 |
does not set <code>new_class_data</code>. If multiple agents |
|
12316 |
have enabled this event the results are chained. That is, if |
|
12317 |
<code>new_class_data</code> has been set, it becomes the |
|
12318 |
<code>class_data</code> for the next agent. |
|
12319 |
<p/> |
|
12320 |
The order that this event is sent to each environment differs |
|
12321 |
from other events. |
|
12322 |
This event is sent to environments in the following order: |
|
12323 |
<ul> |
|
12324 |
<li><fieldlink id="can_retransform_classes" |
|
12325 |
struct="jvmtiCapabilities">retransformation |
|
12326 |
incapable</fieldlink> |
|
12327 |
environments, in the |
|
12328 |
order in which they were created |
|
12329 |
</li> |
|
12330 |
<li><fieldlink id="can_retransform_classes" |
|
12331 |
struct="jvmtiCapabilities">retransformation |
|
12332 |
capable</fieldlink> |
|
12333 |
environments, in the |
|
12334 |
order in which they were created |
|
12335 |
</li> |
|
12336 |
</ul> |
|
12337 |
When triggered by <functionlink id="RetransformClasses"/>, |
|
12338 |
this event is sent only to <fieldlink id="can_retransform_classes" |
|
12339 |
struct="jvmtiCapabilities">retransformation |
|
12340 |
capable</fieldlink> |
|
12341 |
environments. |
|
12342 |
</description> |
|
12343 |
<origin>jvmpi</origin> |
|
12344 |
<capabilities> |
|
12345 |
<capability id="can_generate_all_class_hook_events"></capability> |
|
12346 |
</capabilities> |
|
12347 |
<parameters> |
|
12348 |
<param id="jni_env"> |
|
12349 |
<outptr> |
|
12350 |
<struct>JNIEnv</struct> |
|
12351 |
</outptr> |
|
12352 |
<description> |
|
12353 |
The JNI environment of the event (current) thread. |
|
12354 |
Will be <code>NULL</code> if sent during the primordial |
|
12355 |
<functionlink id="GetPhase">phase</functionlink>. |
|
12356 |
</description> |
|
12357 |
</param> |
|
12358 |
<param id="class_being_redefined"> |
|
12359 |
<jclass/> |
|
12360 |
<description> |
|
12361 |
The class being |
|
12362 |
<functionlink id="RedefineClasses">redefined</functionlink> or |
|
12363 |
<functionlink id="RetransformClasses">retransformed</functionlink>. |
|
12364 |
<code>NULL</code> if sent by class load. |
|
12365 |
</description> |
|
12366 |
</param> |
|
12367 |
<param id="loader"> |
|
12368 |
<jobject/> |
|
12369 |
<description> |
|
12370 |
The class loader loading the class. |
|
12371 |
<code>NULL</code> if the bootstrap class loader. |
|
12372 |
</description> |
|
12373 |
</param> |
|
12374 |
<param id="name"> |
|
12375 |
<vmbuf><char/></vmbuf> |
|
12376 |
<description> |
|
12377 |
Name of class being loaded as a VM internal qualified name |
|
12378 |
(for example, "java/util/List"), encoded as a |
|
12379 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
12380 |
Note: if the class is defined with a <code>NULL</code> name or |
|
12381 |
without a name specified, <code>name</code> will be <code>NULL</code>. |
|
12382 |
</description> |
|
12383 |
</param> |
|
12384 |
<param id="protection_domain"> |
|
12385 |
<jobject/> |
|
12386 |
<description> |
|
12387 |
The <code>ProtectionDomain</code> of the class. |
|
12388 |
</description> |
|
12389 |
</param> |
|
12390 |
<param id="class_data_len"> |
|
12391 |
<jint/> |
|
12392 |
<description> |
|
12393 |
Length of current class file data buffer. |
|
12394 |
</description> |
|
12395 |
</param> |
|
12396 |
<param id="class_data"> |
|
12397 |
<vmbuf><uchar/></vmbuf> |
|
12398 |
<description> |
|
12399 |
Pointer to the current class file data buffer. |
|
12400 |
</description> |
|
12401 |
</param> |
|
12402 |
<param id="new_class_data_len"> |
|
12403 |
<outptr><jint/></outptr> |
|
12404 |
<description> |
|
12405 |
Pointer to the length of the new class file data buffer. |
|
12406 |
</description> |
|
12407 |
</param> |
|
12408 |
<param id="new_class_data"> |
|
12409 |
<agentbuf incount="new_class_data_len"><uchar/></agentbuf> |
|
12410 |
<description> |
|
12411 |
Pointer to the pointer to the instrumented class file data buffer. |
|
12412 |
</description> |
|
12413 |
</param> |
|
12414 |
</parameters> |
|
12415 |
</event> |
|
12416 |
||
12417 |
<event label="VM Start Event" |
|
12418 |
id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start"> |
|
12419 |
<description> |
|
12420 |
The VM initialization event signals the start of the VM. |
|
12421 |
At this time JNI is live but the VM is not yet fully initialized. |
|
12422 |
Once this event is generated, the agent is free to call any JNI function. |
|
12423 |
This event signals the beginning of the start phase, |
|
12424 |
<jvmti/> functions permitted in the start phase may be called. |
|
12425 |
<p/> |
|
12426 |
In the case of VM start-up failure, this event will not be sent. |
|
12427 |
</description> |
|
12428 |
<origin>jvmdi</origin> |
|
12429 |
<capabilities> |
|
12430 |
</capabilities> |
|
12431 |
<parameters> |
|
12432 |
<param id="jni_env"> |
|
12433 |
<outptr> |
|
12434 |
<struct>JNIEnv</struct> |
|
12435 |
</outptr> |
|
12436 |
<description> |
|
12437 |
The JNI environment of the event (current) thread. |
|
12438 |
</description> |
|
12439 |
</param> |
|
12440 |
</parameters> |
|
12441 |
</event> |
|
12442 |
||
12443 |
<event label="VM Initialization Event" |
|
12444 |
id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50"> |
|
12445 |
<description> |
|
12446 |
The VM initialization event signals the completion of VM initialization. Once |
|
12447 |
this event is generated, the agent is free to call any JNI or <jvmti/> |
|
12448 |
function. The VM initialization event can be preceded by or can be concurrent |
|
12449 |
with other events, but |
|
12450 |
the preceding events should be handled carefully, if at all, because the |
|
12451 |
VM has not completed its initialization. The thread start event for the |
|
12452 |
main application thread is guaranteed not to occur until after the |
|
12453 |
handler for the VM initialization event returns. |
|
12454 |
<p/> |
|
12455 |
In the case of VM start-up failure, this event will not be sent. |
|
12456 |
</description> |
|
12457 |
<origin>jvmdi</origin> |
|
12458 |
<capabilities> |
|
12459 |
</capabilities> |
|
12460 |
<parameters> |
|
12461 |
<param id="jni_env"> |
|
12462 |
<outptr> |
|
12463 |
<struct>JNIEnv</struct> |
|
12464 |
</outptr> |
|
12465 |
<description> |
|
12466 |
The JNI environment of the event (current) thread. |
|
12467 |
</description> |
|
12468 |
</param> |
|
12469 |
<param id="thread"> |
|
12470 |
<jthread/> |
|
12471 |
<description> |
|
12472 |
The initial thread |
|
12473 |
</description> |
|
12474 |
</param> |
|
12475 |
</parameters> |
|
12476 |
</event> |
|
12477 |
||
12478 |
<event label="VM Death Event" |
|
12479 |
id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51"> |
|
12480 |
<description> |
|
12481 |
The VM death event notifies the agent of the termination of the VM. |
|
12482 |
No events will occur after the VMDeath event. |
|
12483 |
<p/> |
|
12484 |
In the case of VM start-up failure, this event will not be sent. |
|
12485 |
Note that <internallink id="onunload">Agent_OnUnload</internallink> |
|
12486 |
will still be called in these cases. |
|
12487 |
</description> |
|
12488 |
<origin>jvmdi</origin> |
|
12489 |
<capabilities> |
|
12490 |
</capabilities> |
|
12491 |
<parameters> |
|
12492 |
<param id="jni_env"> |
|
12493 |
<outptr> |
|
12494 |
<struct>JNIEnv</struct> |
|
12495 |
</outptr> |
|
12496 |
<description> |
|
12497 |
The JNI environment of the event (current) thread |
|
12498 |
</description> |
|
12499 |
</param> |
|
12500 |
</parameters> |
|
12501 |
</event> |
|
12502 |
||
12503 |
<event label="Compiled Method Load" |
|
12504 |
id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68"> |
|
12505 |
<description> |
|
12506 |
Sent when a method is compiled and loaded into memory by the VM. |
|
12507 |
If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent. |
|
12508 |
If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent, |
|
12509 |
followed by a new <code>CompiledMethodLoad</code> event. |
|
12510 |
Note that a single method may have multiple compiled forms, and that |
|
12511 |
this event will be sent for each form. |
|
12512 |
Note also that several methods may be inlined into a single |
|
12513 |
address range, and that this event will be sent for each method. |
|
12514 |
<p/> |
|
12515 |
These events can be sent after their initial occurrence with |
|
12516 |
<functionlink id="GenerateEvents"></functionlink>. |
|
12517 |
</description> |
|
12518 |
<origin>jvmpi</origin> |
|
12519 |
<typedef id="jvmtiAddrLocationMap" label="Native address to location entry"> |
|
12520 |
<field id="start_address"> |
|
12521 |
<vmbuf><void/></vmbuf> |
|
12522 |
<description> |
|
12523 |
Starting native address of code corresponding to a location |
|
12524 |
</description> |
|
12525 |
</field> |
|
12526 |
<field id="location"> |
|
12527 |
<jlocation/> |
|
12528 |
<description> |
|
12529 |
Corresponding location. See |
|
12530 |
<functionlink id="GetJLocationFormat"></functionlink> |
|
12531 |
for the meaning of location. |
|
12532 |
</description> |
|
12533 |
</field> |
|
12534 |
</typedef> |
|
12535 |
<capabilities> |
|
12536 |
<required id="can_generate_compiled_method_load_events"></required> |
|
12537 |
</capabilities> |
|
12538 |
<parameters> |
|
12539 |
<param id="klass"> |
|
12540 |
<jclass method="method"/> |
|
12541 |
<description> |
|
12542 |
Class of the method being compiled and loaded |
|
12543 |
</description> |
|
12544 |
</param> |
|
12545 |
<param id="method"> |
|
12546 |
<jmethodID class="klass"/> |
|
12547 |
<description> |
|
12548 |
Method being compiled and loaded |
|
12549 |
</description> |
|
12550 |
</param> |
|
12551 |
<param id="code_size"> |
|
12552 |
<jint/> |
|
12553 |
<description> |
|
12554 |
Size of compiled code |
|
12555 |
</description> |
|
12556 |
</param> |
|
12557 |
<param id="code_addr"> |
|
12558 |
<vmbuf><void/></vmbuf> |
|
12559 |
<description> |
|
12560 |
Address where compiled method code is loaded |
|
12561 |
</description> |
|
12562 |
</param> |
|
12563 |
<param id="map_length"> |
|
12564 |
<jint/> |
|
12565 |
<description> |
|
12566 |
Number of <typelink id="jvmtiAddrLocationMap"></typelink> |
|
12567 |
entries in the address map. |
|
12568 |
Zero if mapping information cannot be supplied. |
|
12569 |
</description> |
|
12570 |
</param> |
|
12571 |
<param id="map"> |
|
12572 |
<vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf> |
|
12573 |
<description> |
|
12574 |
Map from native addresses to location. |
|
12575 |
The native address range of each entry is from |
|
12576 |
<fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink> |
|
12577 |
to <code>start_address-1</code> of the next entry. |
|
12578 |
<code>NULL</code> if mapping information cannot be supplied. |
|
12579 |
</description> |
|
12580 |
</param> |
|
12581 |
<param id="compile_info"> |
|
12582 |
<vmbuf><void/></vmbuf> |
|
12583 |
<description> |
|
12584 |
VM-specific compilation information. |
|
12585 |
The referenced compile information is managed by the VM |
|
12586 |
and must not depend on the agent for collection. |
|
12587 |
A VM implementation defines the content and lifetime |
|
12588 |
of the information. |
|
12589 |
</description> |
|
12590 |
</param> |
|
12591 |
</parameters> |
|
12592 |
</event> |
|
12593 |
||
12594 |
<event label="Compiled Method Unload" |
|
12595 |
id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69"> |
|
12596 |
<description> |
|
12597 |
Sent when a compiled method is unloaded from memory. |
|
12598 |
This event might not be sent on the thread which performed the unload. |
|
12599 |
This event may be sent sometime after the unload occurs, but |
|
12600 |
will be sent before the memory is reused |
|
12601 |
by a newly generated compiled method. This event may be sent after |
|
12602 |
the class is unloaded. |
|
12603 |
</description> |
|
12604 |
<origin>jvmpi</origin> |
|
12605 |
<capabilities> |
|
12606 |
<required id="can_generate_compiled_method_load_events"></required> |
|
12607 |
</capabilities> |
|
12608 |
<parameters> |
|
12609 |
<param id="klass"> |
|
12610 |
<jclass method="method"/> |
|
12611 |
<description> |
|
12612 |
Class of the compiled method being unloaded. |
|
12613 |
</description> |
|
12614 |
</param> |
|
12615 |
<param id="method"> |
|
12616 |
<jmethodID class="klass"/> |
|
12617 |
<description> |
|
12618 |
Compiled method being unloaded. |
|
12619 |
For identification of the compiled method only -- the class |
|
12620 |
may be unloaded and therefore the method should not be used |
|
12621 |
as an argument to further JNI or <jvmti/> functions. |
|
12622 |
</description> |
|
12623 |
</param> |
|
12624 |
<param id="code_addr"> |
|
12625 |
<vmbuf><void/></vmbuf> |
|
12626 |
<description> |
|
12627 |
Address where compiled method code was loaded. |
|
12628 |
For identification of the compiled method only -- |
|
12629 |
the space may have been reclaimed. |
|
12630 |
</description> |
|
12631 |
</param> |
|
12632 |
</parameters> |
|
12633 |
</event> |
|
12634 |
||
12635 |
<event label="Dynamic Code Generated" phase="any" |
|
12636 |
id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70"> |
|
12637 |
<description> |
|
12638 |
Sent when a component of the virtual machine is generated dynamically. |
|
12639 |
This does not correspond to Java programming language code that is |
|
12640 |
compiled--see <eventlink id="CompiledMethodLoad"></eventlink>. |
|
12641 |
This is for native code--for example, an interpreter that is generated |
|
12642 |
differently depending on command-line options. |
|
12643 |
<p/> |
|
12644 |
Note that this event has no controlling capability. |
|
12645 |
If a VM cannot generate these events, it simply does not send any. |
|
12646 |
<p/> |
|
12647 |
These events can be sent after their initial occurrence with |
|
12648 |
<functionlink id="GenerateEvents"></functionlink>. |
|
12649 |
</description> |
|
12650 |
<origin>jvmpi</origin> |
|
12651 |
<capabilities> |
|
12652 |
</capabilities> |
|
12653 |
<parameters> |
|
12654 |
<param id="name"> |
|
12655 |
<vmbuf><char/></vmbuf> |
|
12656 |
<description> |
|
12657 |
Name of the code, encoded as a |
|
12658 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
12659 |
Intended for display to an end-user. |
|
12660 |
The name might not be unique. |
|
12661 |
</description> |
|
12662 |
</param> |
|
12663 |
<param id="address"> |
|
12664 |
<vmbuf><void/></vmbuf> |
|
12665 |
<description> |
|
12666 |
Native address of the code |
|
12667 |
</description> |
|
12668 |
</param> |
|
12669 |
<param id="length"> |
|
12670 |
<jint/> |
|
12671 |
<description> |
|
12672 |
Length in bytes of the code |
|
12673 |
</description> |
|
12674 |
</param> |
|
12675 |
</parameters> |
|
12676 |
</event> |
|
12677 |
||
12678 |
<event label="Data Dump Request" |
|
12679 |
id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71"> |
|
12680 |
<description> |
|
12681 |
Sent by the VM to request the agent to dump its data. This |
|
12682 |
is just a hint and the agent need not react to this event. |
|
12683 |
This is useful for processing command-line signals from users. For |
|
12684 |
example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris |
|
12685 |
causes the VM to send this event to the agent. |
|
12686 |
</description> |
|
12687 |
<origin>jvmpi</origin> |
|
12688 |
<capabilities> |
|
12689 |
</capabilities> |
|
12690 |
<parameters> |
|
12691 |
</parameters> |
|
12692 |
</event> |
|
12693 |
||
12694 |
<event label="Monitor Contended Enter" |
|
12695 |
id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75"> |
|
12696 |
<description> |
|
12697 |
Sent when a thread is attempting to enter a Java programming language |
|
12698 |
monitor already acquired by another thread. |
|
12699 |
</description> |
|
12700 |
<origin>jvmpi</origin> |
|
12701 |
<capabilities> |
|
12702 |
<required id="can_generate_monitor_events"></required> |
|
12703 |
</capabilities> |
|
12704 |
<parameters> |
|
12705 |
<param id="jni_env"> |
|
12706 |
<outptr> |
|
12707 |
<struct>JNIEnv</struct> |
|
12708 |
</outptr> |
|
12709 |
<description> |
|
12710 |
The JNI environment of the event (current) thread |
|
12711 |
</description> |
|
12712 |
</param> |
|
12713 |
<param id="thread"> |
|
12714 |
<jthread/> |
|
12715 |
<description> |
|
12716 |
JNI local reference to the thread |
|
12717 |
attempting to enter the monitor |
|
12718 |
</description> |
|
12719 |
</param> |
|
12720 |
<param id="object"> |
|
12721 |
<jobject/> |
|
12722 |
<description> |
|
12723 |
JNI local reference to the monitor |
|
12724 |
</description> |
|
12725 |
</param> |
|
12726 |
</parameters> |
|
12727 |
</event> |
|
12728 |
||
12729 |
<event label="Monitor Contended Entered" |
|
12730 |
id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76"> |
|
12731 |
<description> |
|
12732 |
Sent when a thread enters a Java programming language |
|
12733 |
monitor after waiting for it to be released by another thread. |
|
12734 |
</description> |
|
12735 |
<origin>jvmpi</origin> |
|
12736 |
<capabilities> |
|
12737 |
<required id="can_generate_monitor_events"></required> |
|
12738 |
</capabilities> |
|
12739 |
<parameters> |
|
12740 |
<param id="jni_env"> |
|
12741 |
<outptr> |
|
12742 |
<struct>JNIEnv</struct> |
|
12743 |
</outptr> |
|
12744 |
<description> |
|
12745 |
The JNI environment of the event (current) thread |
|
12746 |
</description> |
|
12747 |
</param> |
|
12748 |
<param id="thread"> |
|
12749 |
<jthread/> |
|
12750 |
<description> |
|
12751 |
JNI local reference to the thread entering |
|
12752 |
the monitor |
|
12753 |
</description> |
|
12754 |
</param> |
|
12755 |
<param id="object"> |
|
12756 |
<jobject/> |
|
12757 |
<description> |
|
12758 |
JNI local reference to the monitor |
|
12759 |
</description> |
|
12760 |
</param> |
|
12761 |
</parameters> |
|
12762 |
</event> |
|
12763 |
||
12764 |
<event label="Monitor Wait" |
|
12765 |
id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73"> |
|
12766 |
<description> |
|
12767 |
Sent when a thread is about to wait on an object. |
|
12768 |
</description> |
|
12769 |
<origin>jvmpi</origin> |
|
12770 |
<capabilities> |
|
12771 |
<required id="can_generate_monitor_events"></required> |
|
12772 |
</capabilities> |
|
12773 |
<parameters> |
|
12774 |
<param id="jni_env"> |
|
12775 |
<outptr> |
|
12776 |
<struct>JNIEnv</struct> |
|
12777 |
</outptr> |
|
12778 |
<description> |
|
12779 |
The JNI environment of the event (current) thread |
|
12780 |
</description> |
|
12781 |
</param> |
|
12782 |
<param id="thread"> |
|
12783 |
<jthread/> |
|
12784 |
<description> |
|
12785 |
JNI local reference to the thread about to wait |
|
12786 |
</description> |
|
12787 |
</param> |
|
12788 |
<param id="object"> |
|
12789 |
<jobject/> |
|
12790 |
<description> |
|
12791 |
JNI local reference to the monitor |
|
12792 |
</description> |
|
12793 |
</param> |
|
12794 |
<param id="timeout"> |
|
12795 |
<jlong/> |
|
12796 |
<description> |
|
12797 |
The number of milliseconds the thread will wait |
|
12798 |
</description> |
|
12799 |
</param> |
|
12800 |
</parameters> |
|
12801 |
</event> |
|
12802 |
||
12803 |
<event label="Monitor Waited" |
|
12804 |
id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74"> |
|
12805 |
<description> |
|
12806 |
Sent when a thread finishes waiting on an object. |
|
12807 |
</description> |
|
12808 |
<origin>jvmpi</origin> |
|
12809 |
<capabilities> |
|
12810 |
<required id="can_generate_monitor_events"></required> |
|
12811 |
</capabilities> |
|
12812 |
<parameters> |
|
12813 |
<param id="jni_env"> |
|
12814 |
<outptr> |
|
12815 |
<struct>JNIEnv</struct> |
|
12816 |
</outptr> |
|
12817 |
<description> |
|
12818 |
The JNI environment of the event (current) thread |
|
12819 |
</description> |
|
12820 |
</param> |
|
12821 |
<param id="thread"> |
|
12822 |
<jthread/> |
|
12823 |
<description> |
|
12824 |
JNI local reference to the thread that was finished waiting |
|
12825 |
</description> |
|
12826 |
</param> |
|
12827 |
<param id="object"> |
|
12828 |
<jobject/> |
|
12829 |
<description> |
|
12830 |
JNI local reference to the monitor. |
|
12831 |
</description> |
|
12832 |
</param> |
|
12833 |
<param id="timed_out"> |
|
12834 |
<jboolean/> |
|
12835 |
<description> |
|
12836 |
True if the monitor timed out |
|
12837 |
</description> |
|
12838 |
</param> |
|
12839 |
</parameters> |
|
12840 |
</event> |
|
12841 |
||
12842 |
<event label="Resource Exhausted" |
|
12843 |
id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80" |
|
12844 |
since="1.1"> |
|
12845 |
<description> |
|
12846 |
Sent when a VM resource needed by a running application has been exhausted. |
|
12847 |
Except as required by the optional capabilities, the set of resources |
|
12848 |
which report exhaustion is implementation dependent. |
|
12849 |
<p/> |
|
12850 |
The following bit flags define the properties of the resource exhaustion: |
|
12851 |
<constants id="jvmtiResourceExhaustionFlags" |
|
12852 |
label="Resource Exhaustion Flags" |
|
12853 |
kind="bits" |
|
12854 |
since="1.1"> |
|
12855 |
<constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001"> |
|
12856 |
After this event returns, the VM will throw a |
|
12857 |
<code>java.lang.OutOfMemoryError</code>. |
|
12858 |
</constant> |
|
12859 |
<constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002"> |
|
12860 |
The VM was unable to allocate memory from the <tm>Java</tm> |
|
12861 |
platform <i>heap</i>. |
|
12862 |
The <i>heap</i> is the runtime |
|
12863 |
data area from which memory for all class instances and |
|
12864 |
arrays are allocated. |
|
12865 |
</constant> |
|
12866 |
<constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004"> |
|
12867 |
The VM was unable to create a thread. |
|
12868 |
</constant> |
|
12869 |
</constants> |
|
12870 |
</description> |
|
12871 |
<origin>new</origin> |
|
12872 |
<capabilities> |
|
12873 |
<capability id="can_generate_resource_exhaustion_heap_events"> |
|
12874 |
Can generate events when the VM is unable to allocate memory from the |
|
12875 |
<internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>. |
|
12876 |
</capability> |
|
12877 |
<capability id="can_generate_resource_exhaustion_threads_events"> |
|
12878 |
Can generate events when the VM is unable to |
|
12879 |
<internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create |
|
12880 |
a thread</internallink>. |
|
12881 |
</capability> |
|
12882 |
</capabilities> |
|
12883 |
<parameters> |
|
12884 |
<param id="jni_env"> |
|
12885 |
<outptr> |
|
12886 |
<struct>JNIEnv</struct> |
|
12887 |
</outptr> |
|
12888 |
<description> |
|
12889 |
The JNI environment of the event (current) thread |
|
12890 |
</description> |
|
12891 |
</param> |
|
12892 |
<param id="flags"> |
|
12893 |
<jint/> |
|
12894 |
<description> |
|
12895 |
Flags defining the properties of the of resource exhaustion |
|
12896 |
as specified by the |
|
12897 |
<internallink id="jvmtiResourceExhaustionFlags">Resource |
|
12898 |
Exhaustion Flags</internallink>. |
|
12899 |
</description> |
|
12900 |
</param> |
|
12901 |
<param id="reserved"> |
|
12902 |
<vmbuf><void/></vmbuf> |
|
12903 |
<description> |
|
12904 |
Reserved. |
|
12905 |
</description> |
|
12906 |
</param> |
|
12907 |
<param id="description"> |
|
12908 |
<vmbuf><char/></vmbuf> |
|
12909 |
<description> |
|
12910 |
Description of the resource exhaustion, encoded as a |
|
12911 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
12912 |
</description> |
|
12913 |
</param> |
|
12914 |
</parameters> |
|
12915 |
</event> |
|
12916 |
||
12917 |
<event label="VM Object Allocation" |
|
12918 |
id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84"> |
|
12919 |
<description> |
|
12920 |
Sent when a method causes the virtual machine to allocate an |
|
12921 |
Object visible to Java programming language code and the |
|
12922 |
allocation is not detectable by other intrumentation mechanisms. |
|
12923 |
Generally object allocation should be detected by instrumenting |
|
12924 |
the bytecodes of allocating methods. |
|
12925 |
Object allocation generated in native code by JNI function |
|
12926 |
calls should be detected using |
|
12927 |
<internallink id="jniIntercept">JNI function interception</internallink>. |
|
12928 |
Some methods might not have associated bytecodes and are not |
|
12929 |
native methods, they instead are executed directly by the |
|
12930 |
VM. These methods should send this event. |
|
12931 |
Virtual machines which are incapable of bytecode instrumentation |
|
12932 |
for some or all of their methods can send this event. |
|
12933 |
<p/> |
|
12934 |
Typical examples where this event might be sent: |
|
12935 |
<ul> |
|
12936 |
<li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li> |
|
12937 |
<li>Methods not represented by bytecodes -- for example, VM intrinsics and |
|
12938 |
J2ME preloaded classes</li> |
|
12939 |
</ul> |
|
12940 |
Cases where this event would not be generated: |
|
12941 |
<ul> |
|
12942 |
<li>Allocation due to bytecodes -- for example, the <code>new</code> |
|
12943 |
and <code>newarray</code> VM instructions</li> |
|
12944 |
<li>Allocation due to JNI function calls -- for example, |
|
12945 |
<code>AllocObject</code></li> |
|
12946 |
<li>Allocations during VM initialization</li> |
|
12947 |
<li>VM internal objects</li> |
|
12948 |
</ul> |
|
12949 |
</description> |
|
12950 |
<origin>new</origin> |
|
12951 |
<capabilities> |
|
12952 |
<required id="can_generate_vm_object_alloc_events"></required> |
|
12953 |
</capabilities> |
|
12954 |
<parameters> |
|
12955 |
<param id="jni_env"> |
|
12956 |
<outptr> |
|
12957 |
<struct>JNIEnv</struct> |
|
12958 |
</outptr> |
|
12959 |
<description> |
|
12960 |
The JNI environment of the event (current) thread |
|
12961 |
</description> |
|
12962 |
</param> |
|
12963 |
<param id="thread"> |
|
12964 |
<jthread/> |
|
12965 |
<description> |
|
12966 |
Thread allocating the object. |
|
12967 |
</description> |
|
12968 |
</param> |
|
12969 |
<param id="object"> |
|
12970 |
<jobject/> |
|
12971 |
<description> |
|
12972 |
JNI local reference to the object that was allocated |
|
12973 |
</description> |
|
12974 |
</param> |
|
12975 |
<param id="object_klass"> |
|
12976 |
<jclass/> |
|
12977 |
<description> |
|
12978 |
JNI local reference to the class of the object |
|
12979 |
</description> |
|
12980 |
</param> |
|
12981 |
<param id="size"> |
|
12982 |
<jlong/> |
|
12983 |
<description> |
|
12984 |
Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. |
|
12985 |
</description> |
|
12986 |
</param> |
|
12987 |
</parameters> |
|
12988 |
</event> |
|
12989 |
||
12990 |
<event label="Object Free" |
|
12991 |
id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83"> |
|
12992 |
<description> |
|
12993 |
An Object Free event is sent when the garbage collector frees an object. |
|
12994 |
Events are only sent for tagged objects--see |
|
12995 |
<internallink id="Heap">heap functions</internallink>. |
|
12996 |
<p/> |
|
12997 |
The event handler must not use JNI functions and |
|
12998 |
must not use <jvmti/> functions except those which |
|
12999 |
specifically allow such use (see the raw monitor, memory management, |
|
13000 |
and environment local storage functions). |
|
13001 |
</description> |
|
13002 |
<origin>new</origin> |
|
13003 |
<capabilities> |
|
13004 |
<required id="can_generate_object_free_events"></required> |
|
13005 |
</capabilities> |
|
13006 |
<parameters> |
|
13007 |
<param id="tag"> |
|
13008 |
<jlong/> |
|
13009 |
<description> |
|
13010 |
The freed object's tag |
|
13011 |
</description> |
|
13012 |
</param> |
|
13013 |
</parameters> |
|
13014 |
</event> |
|
13015 |
||
13016 |
<event label="Garbage Collection Start" |
|
13017 |
id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81"> |
|
13018 |
<description> |
|
7896
08aadd7aa3ee
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
7724
diff
changeset
|
13019 |
A Garbage Collection Start event is sent when a |
08aadd7aa3ee
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
7724
diff
changeset
|
13020 |
garbage collection pause begins. |
1 | 13021 |
Only stop-the-world collections are reported--that is, collections during |
13022 |
which all threads cease to modify the state of the Java virtual machine. |
|
13023 |
This means that some collectors will never generate these events. |
|
13024 |
This event is sent while the VM is still stopped, thus |
|
13025 |
the event handler must not use JNI functions and |
|
13026 |
must not use <jvmti/> functions except those which |
|
13027 |
specifically allow such use (see the raw monitor, memory management, |
|
13028 |
and environment local storage functions). |
|
13029 |
<p/> |
|
13030 |
This event is always sent as a matched pair with |
|
13031 |
<eventlink id="GarbageCollectionFinish"/> |
|
13032 |
(assuming both events are enabled) and no garbage collection |
|
13033 |
events will occur between them. |
|
13034 |
</description> |
|
13035 |
<origin>new</origin> |
|
13036 |
<capabilities> |
|
13037 |
<required id="can_generate_garbage_collection_events"></required> |
|
13038 |
</capabilities> |
|
13039 |
<parameters> |
|
13040 |
</parameters> |
|
13041 |
</event> |
|
13042 |
||
13043 |
<event label="Garbage Collection Finish" |
|
13044 |
id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82"> |
|
13045 |
<description> |
|
7896
08aadd7aa3ee
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
7724
diff
changeset
|
13046 |
A Garbage Collection Finish event is sent when a |
08aadd7aa3ee
6458402: 3 jvmti tests fail with CMS and +ExplicitGCInvokesConcurrent
kamg
parents:
7724
diff
changeset
|
13047 |
garbage collection pause ends. |
1 | 13048 |
This event is sent while the VM is still stopped, thus |
13049 |
the event handler must not use JNI functions and |
|
13050 |
must not use <jvmti/> functions except those which |
|
13051 |
specifically allow such use (see the raw monitor, memory management, |
|
13052 |
and environment local storage functions). |
|
13053 |
<p/> |
|
13054 |
Some agents may need to do post garbage collection operations that |
|
13055 |
require the use of the disallowed <jvmti/> or JNI functions. For these |
|
13056 |
cases an agent thread can be created which waits on a raw monitor, |
|
13057 |
and the handler for the Garbage Collection Finish event simply |
|
13058 |
notifies the raw monitor |
|
13059 |
<p/> |
|
13060 |
This event is always sent as a matched pair with |
|
13061 |
<eventlink id="GarbageCollectionStart"/> (assuming both events are enabled). |
|
13062 |
<issue> |
|
13063 |
The most important use of this event is to provide timing information, |
|
13064 |
and thus additional information is not required. However, |
|
13065 |
information about the collection which is "free" should be included - |
|
13066 |
what that information is needs to be determined. |
|
13067 |
</issue> |
|
13068 |
</description> |
|
13069 |
<origin>new</origin> |
|
13070 |
<capabilities> |
|
13071 |
<required id="can_generate_garbage_collection_events"></required> |
|
13072 |
</capabilities> |
|
13073 |
<parameters> |
|
13074 |
</parameters> |
|
13075 |
</event> |
|
13076 |
||
13077 |
<elide> |
|
13078 |
<event label="Verbose Output" phase="any" |
|
13079 |
id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85"> |
|
13080 |
<description> |
|
13081 |
Send verbose messages as strings. |
|
13082 |
<issue> |
|
13083 |
This format is extremely fragile, as it can change with each |
|
13084 |
platform, collector and version. Alternatives include: |
|
13085 |
<ul> |
|
13086 |
<li>building off Java programming language M and M APIs</li> |
|
13087 |
<li>XML</li> |
|
13088 |
<li>key/value pairs</li> |
|
13089 |
<li>removing it</li> |
|
13090 |
</ul> |
|
13091 |
</issue> |
|
13092 |
<issue> |
|
13093 |
Though this seemed trivial to implement. |
|
13094 |
In the RI it appears this will be quite complex. |
|
13095 |
</issue> |
|
13096 |
</description> |
|
13097 |
<origin>new</origin> |
|
13098 |
<capabilities> |
|
13099 |
</capabilities> |
|
13100 |
<parameters> |
|
13101 |
<param id="flag"> |
|
13102 |
<enum>jvmtiVerboseFlag</enum> |
|
13103 |
<description> |
|
13104 |
Which verbose output is being sent. |
|
13105 |
</description> |
|
13106 |
</param> |
|
13107 |
<param id="message"> |
|
13108 |
<vmbuf><char/></vmbuf> |
|
13109 |
<description> |
|
13110 |
Message text, encoded as a |
|
13111 |
<internallink id="mUTF">modified UTF-8</internallink> string. |
|
13112 |
</description> |
|
13113 |
</param> |
|
13114 |
</parameters> |
|
13115 |
</event> |
|
13116 |
</elide> |
|
13117 |
||
13118 |
</eventsection> |
|
13119 |
||
13120 |
<datasection> |
|
13121 |
<intro> |
|
13122 |
<jvmti/> extends the data types defined by JNI. |
|
13123 |
</intro> |
|
13124 |
<basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface"> |
|
13125 |
<basetype id="jboolean"> |
|
13126 |
<description> |
|
13127 |
Holds a Java programming language <code>boolean</code>. |
|
13128 |
Unsigned 8 bits. |
|
13129 |
</description> |
|
13130 |
</basetype> |
|
14287 | 13131 |
<basetype id="jchar"> |
13132 |
<description> |
|
13133 |
Holds a Java programming language <code>char</code>. |
|
13134 |
Unsigned 16 bits. |
|
13135 |
</description> |
|
13136 |
</basetype> |
|
1 | 13137 |
<basetype id="jint"> |
13138 |
<description> |
|
13139 |
Holds a Java programming language <code>int</code>. |
|
13140 |
Signed 32 bits. |
|
13141 |
</description> |
|
13142 |
</basetype> |
|
13143 |
<basetype id="jlong"> |
|
13144 |
<description> |
|
13145 |
Holds a Java programming language <code>long</code>. |
|
13146 |
Signed 64 bits. |
|
13147 |
</description> |
|
13148 |
</basetype> |
|
13149 |
<basetype id="jfloat"> |
|
13150 |
<description> |
|
13151 |
Holds a Java programming language <code>float</code>. |
|
13152 |
32 bits. |
|
13153 |
</description> |
|
13154 |
</basetype> |
|
13155 |
<basetype id="jdouble"> |
|
13156 |
<description> |
|
13157 |
Holds a Java programming language <code>double</code>. |
|
13158 |
64 bits. |
|
13159 |
</description> |
|
13160 |
</basetype> |
|
13161 |
<basetype id="jobject"> |
|
13162 |
<description> |
|
13163 |
Holds a Java programming language object. |
|
13164 |
</description> |
|
13165 |
</basetype> |
|
13166 |
<basetype id="jclass"> |
|
13167 |
<description> |
|
13168 |
Holds a Java programming language class. |
|
13169 |
</description> |
|
13170 |
</basetype> |
|
13171 |
<basetype id="jvalue"> |
|
13172 |
<description> |
|
13173 |
Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java |
|
13174 |
programming language value. |
|
13175 |
</description> |
|
13176 |
</basetype> |
|
13177 |
<basetype id="jfieldID"> |
|
13178 |
<description> |
|
13179 |
Identifies a Java programming language field. |
|
13180 |
<code>jfieldID</code>s returned by <jvmti/> functions and events may be |
|
13181 |
safely stored. |
|
13182 |
</description> |
|
13183 |
</basetype> |
|
13184 |
<basetype id="jmethodID"> |
|
13185 |
<description> |
|
13186 |
Identifies a Java programming language method, initializer, or constructor. |
|
13187 |
<code>jmethodID</code>s returned by <jvmti/> functions and events may be |
|
13188 |
safely stored. However, if the class is unloaded, they become invalid |
|
13189 |
and must not be used. |
|
13190 |
</description> |
|
13191 |
</basetype> |
|
13192 |
<basetype id="JNIEnv"> |
|
13193 |
<description> |
|
13194 |
Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>) |
|
13195 |
is a JNI environment. |
|
13196 |
</description> |
|
13197 |
</basetype> |
|
13198 |
</basetypes> |
|
13199 |
||
13200 |
<basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types"> |
|
13201 |
<basetype id="jvmtiEnv"> |
|
13202 |
<description> |
|
13203 |
The <jvmti/> <internallink id="environments">environment</internallink> pointer. |
|
13204 |
See the <internallink id="FunctionSection">Function Section</internallink>. |
|
13205 |
<code>jvmtiEnv</code> points to the |
|
13206 |
<internallink id="FunctionTable">function table</internallink> pointer. |
|
13207 |
</description> |
|
13208 |
</basetype> |
|
13209 |
<basetype id="jthread"> |
|
13210 |
<definition>typedef jobject jthread;</definition> |
|
13211 |
<description> |
|
13212 |
Subtype of <datalink id="jobject"></datalink> that holds a thread. |
|
13213 |
</description> |
|
13214 |
</basetype> |
|
13215 |
<basetype id="jthreadGroup"> |
|
13216 |
<definition>typedef jobject jthreadGroup;</definition> |
|
13217 |
<description> |
|
13218 |
Subtype of <datalink id="jobject"></datalink> that holds a thread group. |
|
13219 |
</description> |
|
13220 |
</basetype> |
|
13221 |
<basetype id="jlocation"> |
|
13222 |
<definition>typedef jlong jlocation;</definition> |
|
13223 |
<description> |
|
13224 |
A 64 bit value, representing a monotonically increasing |
|
13225 |
executable position within a method. |
|
13226 |
<code>-1</code> indicates a native method. |
|
13227 |
See <functionlink id="GetJLocationFormat"></functionlink> for the format on a |
|
13228 |
given VM. |
|
13229 |
</description> |
|
13230 |
</basetype> |
|
13231 |
<basetype id="jrawMonitorID"> |
|
13232 |
<definition>struct _jrawMonitorID; |
|
13233 |
typedef struct _jrawMonitorID *jrawMonitorID;</definition> |
|
13234 |
<description> |
|
13235 |
A raw monitor. |
|
13236 |
</description> |
|
13237 |
</basetype> |
|
13238 |
<basetype id="jvmtiError"> |
|
13239 |
<description> |
|
13240 |
Holds an error return code. |
|
13241 |
See the <internallink id="ErrorSection">Error section</internallink> for possible values. |
|
13242 |
<example> |
|
13243 |
typedef enum { |
|
13244 |
JVMTI_ERROR_NONE = 0, |
|
13245 |
JVMTI_ERROR_INVALID_THREAD = 10, |
|
13246 |
... |
|
13247 |
} jvmtiError; |
|
13248 |
</example> |
|
13249 |
</description> |
|
13250 |
</basetype> |
|
13251 |
<basetype id="jvmtiEvent"> |
|
13252 |
<description> |
|
13253 |
An identifier for an event type. |
|
13254 |
See the <internallink id="EventSection">Event section</internallink> for possible values. |
|
13255 |
It is guaranteed that future versions of this specification will |
|
13256 |
never assign zero as an event type identifier. |
|
13257 |
<example> |
|
13258 |
typedef enum { |
|
13259 |
JVMTI_EVENT_SINGLE_STEP = 1, |
|
13260 |
JVMTI_EVENT_BREAKPOINT = 2, |
|
13261 |
... |
|
13262 |
} jvmtiEvent; |
|
13263 |
</example> |
|
13264 |
</description> |
|
13265 |
</basetype> |
|
13266 |
<basetype id="jvmtiEventCallbacks"> |
|
13267 |
<description> |
|
13268 |
The callbacks used for events. |
|
13269 |
<example> |
|
13270 |
typedef struct { |
|
13271 |
jvmtiEventVMInit VMInit; |
|
13272 |
jvmtiEventVMDeath VMDeath; |
|
13273 |
... |
|
13274 |
} jvmtiEventCallbacks; |
|
13275 |
</example> |
|
13276 |
See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> |
|
13277 |
for the complete structure. |
|
13278 |
<p/> |
|
13279 |
Where, for example, the VM initialization callback is defined: |
|
13280 |
<example> |
|
13281 |
typedef void (JNICALL *jvmtiEventVMInit) |
|
13282 |
(jvmtiEnv *jvmti_env, |
|
13283 |
JNIEnv* jni_env, |
|
13284 |
jthread thread); |
|
13285 |
</example> |
|
13286 |
See the individual events for the callback function definition. |
|
13287 |
</description> |
|
13288 |
</basetype> |
|
13289 |
<basetype id="jniNativeInterface"> |
|
13290 |
<definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition> |
|
13291 |
<description> |
|
13292 |
Typedef for the JNI function table <code>JNINativeInterface</code> |
|
13293 |
defined in the |
|
14287 | 13294 |
<externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>. |
1 | 13295 |
The JNI reference implementation defines this with an underscore. |
13296 |
</description> |
|
13297 |
</basetype> |
|
13298 |
</basetypes> |
|
13299 |
||
13300 |
</datasection> |
|
13301 |
||
13302 |
<issuessection label="Issues"> |
|
13303 |
<intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic"> |
|
13304 |
JVMDI requires that the agent suspend threads before calling |
|
13305 |
certain sensitive functions. JVMPI requires garbage collection to be |
|
13306 |
disabled before calling certain sensitive functions. |
|
13307 |
It was suggested that rather than have this requirement, that |
|
13308 |
VM place itself in a suitable state before performing an |
|
13309 |
operation. This makes considerable sense since each VM |
|
13310 |
knows its requirements and can most easily arrange a |
|
13311 |
safe state. |
|
13312 |
<p/> |
|
13313 |
The ability to externally suspend/resume threads will, of |
|
13314 |
course, remain. The ability to enable/disable garbage collection will not. |
|
13315 |
<p/> |
|
13316 |
This issue is resolved--suspend will not |
|
13317 |
be required. The spec has been updated to reflect this. |
|
13318 |
</intro> |
|
13319 |
||
13320 |
<intro id="stackSampling" label="Resolved Issue: Call Stack Sampling"> |
|
13321 |
There are a variety of approaches to sampling call stacks. |
|
13322 |
The biggest bifurcation is between VM controlled and agent |
|
13323 |
controlled. |
|
13324 |
<p/> |
|
13325 |
This issue is resolved--agent controlled |
|
13326 |
sampling will be the approach. |
|
13327 |
</intro> |
|
13328 |
||
13329 |
<intro id="threadRepresentation" label="Resolved Issue: Thread Representation"> |
|
13330 |
JVMDI represents threads as jthread. JVMPI primarily |
|
13331 |
uses JNIEnv* to represent threads. |
|
13332 |
<p/> |
|
13333 |
The Expert Group has chosen jthread as the representation |
|
13334 |
for threads in <jvmti/>. |
|
13335 |
JNIEnv* is sent by |
|
13336 |
events since it is needed to JNI functions. JNIEnv, per the |
|
13337 |
JNI spec, are not supposed to be used outside their thread. |
|
13338 |
</intro> |
|
13339 |
||
13340 |
<intro id="design" label="Resolved Issue: Method Representation"> |
|
13341 |
The JNI spec allows an implementation to depend on jclass/jmethodID |
|
13342 |
pairs, rather than simply a jmethodID, to reference a method. |
|
13343 |
JVMDI, for consistency, choose the same representation. |
|
13344 |
JVMPI, however, specifies that a jmethodID alone maps to a |
|
13345 |
method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store |
|
13346 |
pointers in jmethodIDs, and as a result, a jmethodID is sufficient. |
|
13347 |
In fact, any JVM implementation that supports JVMPI must have |
|
13348 |
such a representation. |
|
13349 |
<jvmti/> will use jmethodID as a unique representation of a method |
|
13350 |
(no jclass is used). |
|
13351 |
There should be efficiency gains, particularly in |
|
13352 |
functionality like stack dumping, to this representation. |
|
13353 |
<p/> |
|
13354 |
Note that fields were not used in JVMPI and that the access profile |
|
13355 |
of fields differs from methods--for implementation efficiency |
|
13356 |
reasons, a jclass/jfieldID pair will still be needed for field |
|
13357 |
reference. |
|
13358 |
</intro> |
|
13359 |
||
13360 |
<intro id="localReferenceIssue" label="Resolved Issue: Local References"> |
|
13361 |
Functions return local references. |
|
13362 |
</intro> |
|
13363 |
||
13364 |
<intro id="frameRep" label="Resolved Issue: Representation of frames"> |
|
13365 |
In JVMDI, a frame ID is used to represent a frame. Problem with this |
|
13366 |
is that a VM must track when a frame becomes invalid, a far better |
|
13367 |
approach, and the one used in <jvmti/>, is to reference frames by depth. |
|
13368 |
</intro> |
|
13369 |
||
13370 |
<intro id="requiredCapabilities" label="Issue: Required Capabilities"> |
|
13371 |
Currently, having a required capabilities means that the functionality |
|
13372 |
is optional. Capabilities are useful even for required functionality |
|
13373 |
since they can inform the VM is needed set-up. Thus, there should be |
|
13374 |
a set of capabilities that a conformant implementation must provide |
|
13375 |
(if requested during Agent_OnLoad). |
|
13376 |
</intro> |
|
13377 |
||
13378 |
<intro id="taghint" label="Proposal: add tag hint function"> |
|
13379 |
A hint of the percentage of objects that will be tagged would |
|
13380 |
help the VM pick a good implementation. |
|
13381 |
</intro> |
|
13382 |
||
13383 |
<intro id="moreMonitorQueries" label="Request: More Monitor Quires"> |
|
13384 |
How difficult or easy would be to extend the monitor_info category to include |
|
13385 |
<pre> |
|
13386 |
- current number of monitors |
|
13387 |
- enumeration of monitors |
|
13388 |
- enumeration of threads waiting on a given monitor |
|
13389 |
</pre> |
|
13390 |
The reason for my question is the fact that current get_monitor_info support |
|
13391 |
requires the agent to specify a given thread to get the info which is probably |
|
13392 |
OK in the profiling/debugging space, while in the monitoring space the agent |
|
13393 |
could be watching the monitor list and then decide which thread to ask for |
|
13394 |
the info. You might ask why is this important for monitoring .... I think it |
|
13395 |
can aid in the detection/prediction of application contention caused by hot-locks. |
|
13396 |
</intro> |
|
13397 |
</issuessection> |
|
13398 |
||
13399 |
<changehistory id="ChangeHistory" update="09/05/07"> |
|
13400 |
<intro> |
|
13401 |
The <jvmti/> specification is an evolving document with major, minor, |
|
13402 |
and micro version numbers. |
|
13403 |
A released version of the specification is uniquely identified |
|
13404 |
by its major and minor version. |
|
13405 |
The functions, events, and capabilities in this specification |
|
13406 |
indicate a "Since" value which is the major and minor version in |
|
13407 |
which it was introduced. |
|
13408 |
The version of the specification implemented by the VM can |
|
13409 |
be retrieved at runtime with the <functionlink id="GetVersionNumber"/> |
|
13410 |
function. |
|
13411 |
</intro> |
|
13412 |
<change date="14 Nov 2002"> |
|
13413 |
Converted to XML document. |
|
13414 |
</change> |
|
13415 |
<change date="14 Nov 2002"> |
|
13416 |
Elided heap dump functions (for now) since what was there |
|
13417 |
was wrong. |
|
13418 |
</change> |
|
13419 |
<change date="18 Nov 2002"> |
|
13420 |
Added detail throughout. |
|
13421 |
</change> |
|
13422 |
<change date="18 Nov 2002"> |
|
13423 |
Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE. |
|
13424 |
</change> |
|
13425 |
<change date="19 Nov 2002"> |
|
13426 |
Added AsyncGetStackTrace. |
|
13427 |
</change> |
|
13428 |
<change date="19 Nov 2002"> |
|
13429 |
Added jframeID return to GetStackTrace. |
|
13430 |
</change> |
|
13431 |
<change date="19 Nov 2002"> |
|
13432 |
Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there |
|
13433 |
since they are redundant with GetStackTrace. |
|
13434 |
</change> |
|
13435 |
<change date="19 Nov 2002"> |
|
13436 |
Elided ClearAllBreakpoints since it has always been redundant. |
|
13437 |
</change> |
|
13438 |
<change date="19 Nov 2002"> |
|
13439 |
Added GetSystemProperties. |
|
13440 |
</change> |
|
13441 |
<change date="19 Nov 2002"> |
|
13442 |
Changed the thread local storage functions to use jthread. |
|
13443 |
</change> |
|
13444 |
<change date="20 Nov 2002"> |
|
13445 |
Added GetJLocationFormat. |
|
13446 |
</change> |
|
13447 |
<change date="22 Nov 2002"> |
|
13448 |
Added events and introductory text. |
|
13449 |
</change> |
|
13450 |
<change date="22 Nov 2002"> |
|
13451 |
Cross reference type and constant definitions. |
|
13452 |
</change> |
|
13453 |
<change date="24 Nov 2002"> |
|
13454 |
Added DTD. |
|
13455 |
</change> |
|
13456 |
<change date="24 Nov 2002"> |
|
13457 |
Added capabilities function section. |
|
13458 |
</change> |
|
13459 |
<change date="29 Nov 2002"> |
|
13460 |
Assign capabilities to each function and event. |
|
13461 |
</change> |
|
13462 |
<change date="29 Nov 2002"> |
|
13463 |
Add <internallink id="jniIntercept">JNI interception functions</internallink>. |
|
13464 |
</change> |
|
13465 |
<change date="30 Nov 2002"> |
|
13466 |
Auto generate SetEventNotificationMode capabilities. |
|
13467 |
</change> |
|
13468 |
<change date="30 Nov 2002"> |
|
13469 |
Add <eventlink id="VMObjectAlloc"></eventlink> event. |
|
13470 |
</change> |
|
13471 |
<change date="30 Nov 2002"> |
|
13472 |
Add <eventlink id="DynamicCodeGenerated"></eventlink> event. |
|
13473 |
</change> |
|
13474 |
<change date="30 Nov 2002"> |
|
13475 |
Add const to declarations. |
|
13476 |
</change> |
|
13477 |
<change date="30 Nov 2002"> |
|
13478 |
Change method exit and frame pop to send on exception. |
|
13479 |
</change> |
|
13480 |
<change date="1 Dec 2002"> |
|
13481 |
Add ForceGarbageCollection. |
|
13482 |
</change> |
|
13483 |
<change date="2 Dec 2002"> |
|
13484 |
Redo Xrun section; clarify GetStackTrace and add example; |
|
13485 |
Fix width problems; use "agent" consistently. |
|
13486 |
</change> |
|
13487 |
<change date="8 Dec 2002"> |
|
13488 |
Remove previous start-up intro. |
|
13489 |
Add <internallink id="environments"><jvmti/> Environments</internallink> |
|
13490 |
section. |
|
13491 |
</change> |
|
13492 |
<change date="8 Dec 2002"> |
|
13493 |
Add <functionlink id="DisposeEnvironment"></functionlink>. |
|
13494 |
</change> |
|
13495 |
<change date="9 Dec 2002"> |
|
13496 |
Numerous minor updates. |
|
13497 |
</change> |
|
13498 |
<change date="15 Dec 2002"> |
|
13499 |
Add heap profiling functions added: |
|
13500 |
get/set annotation, iterate live objects/heap. |
|
13501 |
Add heap profiling functions place holder added: |
|
13502 |
heap roots. |
|
13503 |
Heap profiling event added: object free. |
|
13504 |
Heap profiling event redesigned: vm object allocation. |
|
13505 |
Heap profiling event placeholders added: garbage collection start/finish. |
|
13506 |
Native method bind event added. |
|
13507 |
</change> |
|
13508 |
<change date="19 Dec 2002"> |
|
13509 |
Revamp suspend/resume functions. |
|
13510 |
Add origin information with jvmdi tag. |
|
13511 |
Misc fixes. |
|
13512 |
</change> |
|
13513 |
<change date="24 Dec 2002"> |
|
13514 |
Add semantics to types. |
|
13515 |
</change> |
|
13516 |
<change date="27 Dec 2002"> |
|
13517 |
Add local reference section. |
|
13518 |
Autogenerate parameter descriptions from types. |
|
13519 |
</change> |
|
13520 |
<change date="28 Dec 2002"> |
|
13521 |
Document that RunAgentThread sends threadStart. |
|
13522 |
</change> |
|
13523 |
<change date="29 Dec 2002"> |
|
13524 |
Remove redundant local ref and dealloc warning. |
|
13525 |
Convert GetRawMonitorName to allocated buffer. |
|
13526 |
Add GenerateEvents. |
|
13527 |
</change> |
|
13528 |
<change date="30 Dec 2002"> |
|
13529 |
Make raw monitors a type and rename to "jrawMonitorID". |
|
13530 |
</change> |
|
13531 |
<change date="1 Jan 2003"> |
|
13532 |
Include origin information. |
|
13533 |
Clean-up JVMDI issue references. |
|
13534 |
Remove Deallocate warnings which are now automatically generated. |
|
13535 |
</change> |
|
13536 |
<change date="2 Jan 2003"> |
|
13537 |
Fix representation issues for jthread. |
|
13538 |
</change> |
|
13539 |
<change date="3 Jan 2003"> |
|
13540 |
Make capabilities buffered out to 64 bits - and do it automatically. |
|
13541 |
</change> |
|
13542 |
<change date="4 Jan 2003"> |
|
13543 |
Make constants which are enumeration into enum types. |
|
13544 |
Parameters now of enum type. |
|
13545 |
Clean-up and index type section. |
|
13546 |
Replace remaining datadef entities with callback. |
|
13547 |
</change> |
|
13548 |
<change date="7 Jan 2003"> |
|
13549 |
Correct GenerateEvents description. |
|
13550 |
More internal semantics work. |
|
13551 |
</change> |
|
13552 |
<change date="9 Jan 2003"> |
|
13553 |
Replace previous GetSystemProperties with two functions |
|
13554 |
which use allocated information instead fixed. |
|
13555 |
Add SetSystemProperty. |
|
13556 |
More internal semantics work. |
|
13557 |
</change> |
|
13558 |
<change date="12 Jan 2003"> |
|
13559 |
Add varargs to end of SetEventNotificationMode. |
|
13560 |
</change> |
|
13561 |
<change date="20 Jan 2003"> |
|
13562 |
Finish fixing spec to reflect that alloc sizes are jlong. |
|
13563 |
</change> |
|
13564 |
<change date="22 Jan 2003"> |
|
13565 |
Allow NULL as RunAgentThread arg. |
|
13566 |
</change> |
|
13567 |
<change date="22 Jan 2003"> |
|
13568 |
Fixed names to standardized naming convention |
|
13569 |
Removed AsyncGetStackTrace. |
|
13570 |
</change> |
|
13571 |
<change date="29 Jan 2003"> |
|
13572 |
Since we are using jthread, removed GetThread. |
|
13573 |
</change> |
|
13574 |
<change date="31 Jan 2003"> |
|
13575 |
Change GetFieldName to allow NULLs like GetMethodName. |
|
13576 |
</change> |
|
13577 |
<change date="29 Feb 2003" version="v40"> |
|
13578 |
Rewrite the introductory text, adding sections on |
|
13579 |
start-up, environments and bytecode instrumentation. |
|
13580 |
Change the command line arguments per EG discussions. |
|
13581 |
Add an introduction to the capabilities section. |
|
13582 |
Add the extension mechanism category and functions. |
|
13583 |
Mark for deletion, but clarified anyhow, SuspendAllThreads. |
|
13584 |
Rename IterateOverLiveObjects to IterateOverReachableObjects and |
|
13585 |
change the text accordingly. |
|
13586 |
Clarify IterateOverHeap. |
|
13587 |
Clarify CompiledMethodLoad. |
|
13588 |
Discuss prerequisite state for Calling Functions. |
|
13589 |
Clarify SetAllocationHooks. |
|
13590 |
Added issues ("To be resolved:") through-out. |
|
13591 |
And so on... |
|
13592 |
</change> |
|
13593 |
<change date="6 Mar 2003" version="v41"> |
|
13594 |
Remove struct from the call to GetOwnedMonitorInfo. |
|
13595 |
Automatically generate most error documentation, remove |
|
13596 |
(rather broken) hand written error doc. |
|
13597 |
Better describe capability use (empty initial set). |
|
13598 |
Add min value to jint params. |
|
13599 |
Remove the capability can_access_thread_local_storage. |
|
13600 |
Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; |
|
13601 |
same for *NOT_IMPLEMENTED. |
|
13602 |
Description fixes. |
|
13603 |
</change> |
|
13604 |
<change date="8 Mar 2003" version="v42"> |
|
13605 |
Rename GetClassSignature to GetClassName. |
|
13606 |
Rename IterateOverClassObjects to IterateOverInstancesOfClass. |
|
13607 |
Remove GetMaxStack (operand stack isn't used in <jvmti/>). |
|
13608 |
Description fixes: define launch-time, remove native frame pop |
|
13609 |
from PopFrame, and assorted clarifications. |
|
13610 |
</change> |
|
13611 |
<change date="8 Mar 2003" version="v43"> |
|
13612 |
Fix minor editing problem. |
|
13613 |
</change> |
|
13614 |
<change date="10 Mar 2003" version="v44"> |
|
13615 |
Add phase information. |
|
13616 |
Remap (compact) event numbers. |
|
13617 |
</change> |
|
13618 |
<change date="11 Mar 2003" version="v45"> |
|
13619 |
More phase information - allow "any". |
|
13620 |
Elide raw monitor queries and events. |
|
13621 |
Minor description fixes. |
|
13622 |
</change> |
|
13623 |
<change date="12 Mar 2003" version="v46"> |
|
13624 |
Add GetPhase. |
|
13625 |
Use "phase" through document. |
|
13626 |
Elide GetRawMonitorName. |
|
13627 |
Elide GetObjectMonitors. |
|
13628 |
</change> |
|
13629 |
<change date="12 Mar 2003" version="v47"> |
|
13630 |
Fixes from link, XML, and spell checking. |
|
13631 |
Auto-generate the callback structure. |
|
13632 |
</change> |
|
13633 |
<change date="13 Mar 2003" version="v48"> |
|
13634 |
One character XML fix. |
|
13635 |
</change> |
|
13636 |
<change date="13 Mar 2003" version="v49"> |
|
13637 |
Change function parameter names to be consistent with |
|
13638 |
event parameters (fooBarBaz becomes foo_bar_baz). |
|
13639 |
</change> |
|
13640 |
<change date="14 Mar 2003" version="v50"> |
|
13641 |
Fix broken link. Fix thread markers. |
|
13642 |
</change> |
|
13643 |
<change date="14 Mar 2003" version="v51"> |
|
13644 |
Change constants so they are under 128 to workaround |
|
13645 |
compiler problems. |
|
13646 |
</change> |
|
13647 |
<change date="23 Mar 2003" version="v52"> |
|
13648 |
Overhaul capabilities. Separate GetStackTrace into |
|
13649 |
GetStackTrace and GetStackFrames. |
|
13650 |
</change> |
|
13651 |
<change date="8 Apr 2003" version="v54"> |
|
13652 |
Use depth instead of jframeID to reference frames. |
|
13653 |
Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. |
|
13654 |
Remove frame arg from events. |
|
13655 |
</change> |
|
13656 |
<change date="9 Apr 2003" version="v55"> |
|
13657 |
Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. |
|
13658 |
Add missing annotation_count to GetObjectsWithAnnotations |
|
13659 |
</change> |
|
13660 |
<change date="10 Apr 2003" version="v56"> |
|
13661 |
Remove confusing parenthetical statement in GetObjectsWithAnnotations |
|
13662 |
</change> |
|
13663 |
<change date="13 Apr 2003" version="v58"> |
|
13664 |
Replace jclass/jmethodID representation of method with simply jmethodID; |
|
13665 |
Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. |
|
13666 |
Replace can_access_frames with can_access_local_variables; remove from purely stack access. |
|
13667 |
Use can_get_synthetic_attribute; fix description. |
|
13668 |
Clarify that zero length arrays must be deallocated. |
|
13669 |
Clarify RelinquishCapabilities. |
|
13670 |
Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE. |
|
13671 |
</change> |
|
13672 |
<change date="27 Apr 2003" version="v59"> |
|
13673 |
Remove lingering indirect references to OBSOLETE_METHOD_ID. |
|
13674 |
</change> |
|
13675 |
<change date="4 May 2003" version="v60"> |
|
13676 |
Allow DestroyRawMonitor during OnLoad. |
|
13677 |
</change> |
|
13678 |
<change date="7 May 2003" version="v61"> |
|
13679 |
Added not monitor owner error return to DestroyRawMonitor. |
|
13680 |
</change> |
|
13681 |
<change date="13 May 2003" version="v62"> |
|
13682 |
Clarify semantics of raw monitors. |
|
13683 |
Change flags on <code>GetThreadStatus</code>. |
|
13684 |
<code>GetClassLoader</code> return NULL for the bootstrap class loader. |
|
13685 |
Add <code>GetClassName</code> issue. |
|
13686 |
Define local variable signature. |
|
13687 |
Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>. |
|
13688 |
Remove over specification in <code>GetObjectsWithAnnotations</code>. |
|
13689 |
Elide <code>SetAllocationHooks</code>. |
|
13690 |
Elide <code>SuspendAllThreads</code>. |
|
13691 |
</change> |
|
13692 |
<change date="14 May 2003" version="v63"> |
|
13693 |
Define the data type <code>jvmtiEventCallbacks</code>. |
|
13694 |
Zero length allocations return NULL. |
|
13695 |
Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>. |
|
13696 |
Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED. |
|
13697 |
</change> |
|
13698 |
<change date="15 May 2003" version="v64"> |
|
13699 |
Better wording, per review. |
|
13700 |
</change> |
|
13701 |
<change date="15 May 2003" version="v65"> |
|
13702 |
First Alpha. |
|
13703 |
Make jmethodID and jfieldID unique, jclass not used. |
|
13704 |
</change> |
|
13705 |
<change date="27 May 2003" version="v66"> |
|
13706 |
Fix minor XSLT errors. |
|
13707 |
</change> |
|
13708 |
<change date="13 June 2003" version="v67"> |
|
13709 |
Undo making jfieldID unique (jmethodID still is). |
|
13710 |
</change> |
|
13711 |
<change date="17 June 2003" version="v68"> |
|
13712 |
Changes per June 11th Expert Group meeting -- |
|
13713 |
Overhaul Heap functionality: single callback, |
|
13714 |
remove GetHeapRoots, add reachable iterators, |
|
13715 |
and rename "annotation" to "tag". |
|
13716 |
NULL thread parameter on most functions is current |
|
13717 |
thread. |
|
13718 |
Add timers. |
|
13719 |
Remove ForceExit. |
|
13720 |
Add GetEnvironmentLocalStorage. |
|
13721 |
Add verbose flag and event. |
|
13722 |
Add AddToBootstrapClassLoaderSearch. |
|
13723 |
Update ClassFileLoadHook. |
|
13724 |
</change> |
|
13725 |
<change date="18 June 2003" version="v69"> |
|
13726 |
Clean up issues sections. |
|
13727 |
Rename GetClassName back to GetClassSignature and |
|
13728 |
fix description. |
|
13729 |
Add generic signature to GetClassSignature, |
|
13730 |
GetFieldSignature, GetMethodSignature, and |
|
13731 |
GetLocalVariableTable. |
|
13732 |
Elide EstimateCostOfCapabilities. |
|
13733 |
Clarify that the system property functions operate |
|
13734 |
on the VM view of system properties. |
|
13735 |
Clarify Agent_OnLoad. |
|
13736 |
Remove "const" from JNIEnv* in events. |
|
13737 |
Add metadata accessors. |
|
13738 |
</change> |
|
13739 |
<change date="18 June 2003" version="v70"> |
|
13740 |
Add start_depth to GetStackTrace. |
|
13741 |
Move system properties to a new category. |
|
13742 |
Add GetObjectSize. |
|
13743 |
Remove "X" from command line flags. |
|
13744 |
XML, HTML, and spell check corrections. |
|
13745 |
</change> |
|
13746 |
<change date="19 June 2003" version="v71"> |
|
13747 |
Fix JVMTI_HEAP_ROOT_THREAD to be 6. |
|
13748 |
Make each synopsis match the function name. |
|
13749 |
Fix unclear wording. |
|
13750 |
</change> |
|
13751 |
<change date="26 June 2003" version="v72"> |
|
13752 |
SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value |
|
13753 |
to be set to NULL. |
|
13754 |
NotifyFramePop, GetFrameLocationm and all the local variable operations |
|
13755 |
needed to have their wording about frames fixed. |
|
13756 |
Grammar and clarity need to be fixed throughout. |
|
13757 |
Capitalization and puntuation need to be consistent. |
|
13758 |
Need micro version number and masks for accessing major, minor, and micro. |
|
13759 |
The error code lists should indicate which must be returned by |
|
13760 |
an implementation. |
|
13761 |
The command line properties should be visible in the properties functions. |
|
13762 |
Disallow popping from the current thread. |
|
13763 |
Allow implementations to return opaque frame error when they cannot pop. |
|
13764 |
The NativeMethodBind event should be sent during any phase. |
|
13765 |
The DynamicCodeGenerated event should be sent during any phase. |
|
13766 |
The following functions should be allowed to operate before VMInit: |
|
13767 |
Set/GetEnvironmentLocalStorage |
|
13768 |
GetMethodDeclaringClass |
|
13769 |
GetClassSignature |
|
13770 |
GetClassModifiers |
|
13771 |
IsInterface |
|
13772 |
IsArrayClass |
|
13773 |
GetMethodName |
|
13774 |
GetMethodModifiers |
|
13775 |
GetMaxLocals |
|
13776 |
GetArgumentsSize |
|
13777 |
GetLineNumberTable |
|
13778 |
GetMethodLocation |
|
13779 |
IsMethodNative |
|
13780 |
IsMethodSynthetic. |
|
13781 |
Other changes (to XSL): |
|
13782 |
Argument description should show asterisk after not before pointers. |
|
13783 |
NotifyFramePop, GetFrameLocationm and all the local variable operations |
|
13784 |
should hsve the NO_MORE_FRAMES error added. |
|
13785 |
Not alive threads should have a different error return than invalid thread. |
|
13786 |
</change> |
|
13787 |
<change date="7 July 2003" version="v73"> |
|
13788 |
VerboseOutput event was missing message parameter. |
|
13789 |
Minor fix-ups. |
|
13790 |
</change> |
|
13791 |
<change date="14 July 2003" version="v74"> |
|
13792 |
Technical Publications Department corrections. |
|
13793 |
Allow thread and environment local storage to be set to NULL. |
|
13794 |
</change> |
|
13795 |
<change date="23 July 2003" version="v75"> |
|
13796 |
Use new Agent_OnLoad rather than overloaded JVM_OnLoad. |
|
13797 |
Add JNICALL to callbacks (XSL). |
|
13798 |
Document JNICALL requirement for both events and callbacks (XSL). |
|
13799 |
Restrict RedefineClasses to methods and attributes. |
|
13800 |
Elide the VerboseOutput event. |
|
13801 |
VMObjectAlloc: restrict when event is sent and remove method parameter. |
|
13802 |
Finish loose ends from Tech Pubs edit. |
|
13803 |
</change> |
|
13804 |
<change date="24 July 2003" version="v76"> |
|
13805 |
Change ClassFileLoadHook event to send the class instead of a boolean of redefine. |
|
13806 |
</change> |
|
13807 |
<change date="24 July 2003" version="v77"> |
|
13808 |
XML fixes. |
|
13809 |
Minor text clarifications and corrections. |
|
13810 |
</change> |
|
13811 |
<change date="24 July 2003" version="v78"> |
|
13812 |
Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>. |
|
13813 |
Clarify that stack frames are JVM Spec frames. |
|
13814 |
Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, |
|
13815 |
and can_get_source_debug_extension. |
|
13816 |
PopFrame cannot have a native calling method. |
|
13817 |
Removed incorrect statement in GetClassloaderClasses |
|
9431
e3bea7d56a98
7033669: JVM TI spec has to be changed to not contain URLS to the VM Spec
kamg
parents:
7896
diff
changeset
|
13818 |
(see <vmspec chapter="4.4"/>). |
1 | 13819 |
</change> |
13820 |
<change date="24 July 2003" version="v79"> |
|
13821 |
XML and text fixes. |
|
13822 |
Move stack frame description into Stack Frame category. |
|
13823 |
</change> |
|
13824 |
<change date="26 July 2003" version="v80"> |
|
13825 |
Allow NULL (means bootstrap loader) for GetClassloaderClasses. |
|
13826 |
Add new heap reference kinds for references from classes. |
|
13827 |
Add timer information struct and query functions. |
|
13828 |
Add AvailableProcessors. |
|
13829 |
Rename GetOtherThreadCpuTime to GetThreadCpuTime. |
|
13830 |
Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE |
|
13831 |
to SetEventNotification mode. |
|
13832 |
Add initial thread to the VM_INIT event. |
|
13833 |
Remove platform assumptions from AddToBootstrapClassLoaderSearch. |
|
13834 |
</change> |
|
13835 |
<change date="26 July 2003" version="v81"> |
|
13836 |
Grammar and clarity changes per review. |
|
13837 |
</change> |
|
13838 |
<change date="27 July 2003" version="v82"> |
|
13839 |
More grammar and clarity changes per review. |
|
13840 |
Add Agent_OnUnload. |
|
13841 |
</change> |
|
13842 |
<change date="28 July 2003" version="v83"> |
|
13843 |
Change return type of Agent_OnUnload to void. |
|
13844 |
</change> |
|
13845 |
<change date="28 July 2003" version="v84"> |
|
13846 |
Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT. |
|
13847 |
</change> |
|
13848 |
<change date="28 July 2003" version="v85"> |
|
13849 |
Steal java.lang.Runtime.availableProcessors() wording for |
|
13850 |
AvailableProcessors(). |
|
13851 |
Guarantee that zero will never be an event ID. |
|
13852 |
Remove some issues which are no longer issues. |
|
13853 |
Per review, rename and more completely document the timer |
|
13854 |
information functions. |
|
13855 |
</change> |
|
13856 |
<change date="29 July 2003" version="v86"> |
|
13857 |
Non-spec visible change to XML controlled implementation: |
|
13858 |
SetThreadLocalStorage must run in VM mode. |
|
13859 |
</change> |
|
13860 |
<change date="5 August 2003" version="0.1.87"> |
|
13861 |
Add GetErrorName. |
|
13862 |
Add varargs warning to jvmtiExtensionEvent. |
|
13863 |
Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. |
|
13864 |
Remove unused can_get_exception_info capability. |
|
13865 |
Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. |
|
13866 |
Fix jvmtiExtensionFunctionInfo.func declared type. |
|
13867 |
Extension function returns error code. |
|
13868 |
Use new version numbering. |
|
13869 |
</change> |
|
13870 |
<change date="5 August 2003" version="0.2.88"> |
|
13871 |
Remove the ClassUnload event. |
|
13872 |
</change> |
|
13873 |
<change date="8 August 2003" version="0.2.89"> |
|
13874 |
Heap reference iterator callbacks return an enum that |
|
13875 |
allows outgoing object references to be ignored. |
|
13876 |
Allow JNIEnv as a param type to extension events/functions. |
|
13877 |
</change> |
|
13878 |
<change date="15 August 2003" version="0.2.90"> |
|
13879 |
Fix a typo. |
|
13880 |
</change> |
|
13881 |
<change date="2 September 2003" version="0.2.91"> |
|
13882 |
Remove all metadata functions: GetClassMetadata, |
|
13883 |
GetFieldMetadata, and GetMethodMetadata. |
|
13884 |
</change> |
|
13885 |
<change date="1 October 2003" version="0.2.92"> |
|
13886 |
Mark the functions Allocate. Deallocate, RawMonitor*, |
|
13887 |
SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage |
|
13888 |
as safe for use in heap callbacks and GC events. |
|
13889 |
</change> |
|
13890 |
<change date="24 November 2003" version="0.2.93"> |
|
13891 |
Add pass through opaque user data pointer to heap iterate |
|
13892 |
functions and callbacks. |
|
13893 |
In the CompiledMethodUnload event, send the code address. |
|
13894 |
Add GarbageCollectionOccurred event. |
|
13895 |
Add constant pool reference kind. |
|
13896 |
Mark the functions CreateRawMonitor and DestroyRawMonitor |
|
13897 |
as safe for use in heap callbacks and GC events. |
|
13898 |
Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, |
|
13899 |
GetThreadCpuTimerInfo, IterateOverReachableObjects, |
|
13900 |
IterateOverObjectsReachableFromObject, GetTime and |
|
13901 |
JVMTI_ERROR_NULL_POINTER. |
|
13902 |
Add missing errors to: GenerateEvents and |
|
13903 |
AddToBootstrapClassLoaderSearch. |
|
13904 |
Fix description of ClassFileLoadHook name parameter. |
|
13905 |
In heap callbacks and GC/ObjectFree events, specify |
|
13906 |
that only explicitly allowed functions can be called. |
|
13907 |
Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, |
|
13908 |
GetTimerInfo, and GetTime during callback. |
|
13909 |
Allow calling SetTag/GetTag during the onload phase. |
|
13910 |
SetEventNotificationMode, add: error attempted inappropriate |
|
13911 |
thread level control. |
|
13912 |
Remove jvmtiExceptionHandlerEntry. |
|
13913 |
Fix handling of native methods on the stack -- |
|
13914 |
location_ptr param of GetFrameLocation, remove |
|
13915 |
JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, |
|
13916 |
jvmtiFrameInfo.location, and jlocation. |
|
13917 |
Remove typo (from JVMPI) implying that the MonitorWaited |
|
13918 |
event is sent on sleep. |
|
13919 |
</change> |
|
13920 |
<change date="25 November 2003" version="0.2.94"> |
|
13921 |
Clarifications and typos. |
|
13922 |
</change> |
|
13923 |
<change date="3 December 2003" version="0.2.95"> |
|
13924 |
Allow NULL user_data in heap iterators. |
|
13925 |
</change> |
|
13926 |
<change date="28 January 2004" version="0.2.97"> |
|
13927 |
Add GetThreadState, deprecate GetThreadStatus. |
|
13928 |
</change> |
|
13929 |
<change date="29 January 2004" version="0.2.98"> |
|
13930 |
INVALID_SLOT and TYPE_MISMATCH errors should be optional. |
|
13931 |
</change> |
|
13932 |
<change date="12 February 2004" version="0.2.102"> |
|
13933 |
Remove MonitorContendedExit. |
|
13934 |
Added JNIEnv parameter to VMObjectAlloc. |
|
13935 |
Clarified definition of class_tag and referrer_index |
|
13936 |
parameters to heap callbacks. |
|
13937 |
</change> |
|
13938 |
<change date="16 Febuary 2004" version="0.2.103"> |
|
13939 |
Document JAVA_TOOL_OPTIONS. |
|
13940 |
</change> |
|
13941 |
<change date="17 Febuary 2004" version="0.2.105"> |
|
13942 |
Divide start phase into primordial and start. |
|
13943 |
Add VMStart event |
|
13944 |
Change phase associations of functions and events. |
|
13945 |
</change> |
|
13946 |
<change date="18 Febuary 2004" version="0.3.6"> |
|
13947 |
Elide deprecated GetThreadStatus. |
|
13948 |
Bump minor version, subtract 100 from micro version |
|
13949 |
</change> |
|
13950 |
<change date="18 Febuary 2004" version="0.3.7"> |
|
13951 |
Document that timer nanosecond values are unsigned. |
|
13952 |
Clarify text having to do with native methods. |
|
13953 |
</change> |
|
13954 |
<change date="19 Febuary 2004" version="0.3.8"> |
|
13955 |
Fix typos. |
|
13956 |
Remove elided deprecated GetThreadStatus. |
|
13957 |
</change> |
|
13958 |
<change date="23 Febuary 2004" version="0.3.9"> |
|
13959 |
Require NotifyFramePop to act on suspended threads. |
|
13960 |
</change> |
|
13961 |
<change date="24 Febuary 2004" version="0.3.10"> |
|
13962 |
Add capabilities |
|
13963 |
(<internallink id="jvmtiCapabilities.can_redefine_any_class" |
|
13964 |
><code>can_redefine_any_class</code></internallink> |
|
13965 |
and |
|
13966 |
<internallink id="jvmtiCapabilities.can_generate_all_class_hook_events" |
|
13967 |
><code>can_generate_all_class_hook_events</code></internallink>) |
|
13968 |
and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) |
|
13969 |
which allow some classes to be unmodifiable. |
|
13970 |
</change> |
|
13971 |
<change date="28 Febuary 2004" version="0.3.11"> |
|
13972 |
Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode. |
|
13973 |
</change> |
|
13974 |
<change date="8 March 2004" version="0.3.12"> |
|
13975 |
Clarified CompiledMethodUnload so that it is clear the event |
|
13976 |
may be posted after the class has been unloaded. |
|
13977 |
</change> |
|
13978 |
<change date="5 March 2004" version="0.3.13"> |
|
13979 |
Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize. |
|
13980 |
</change> |
|
13981 |
<change date="13 March 2004" version="0.3.14"> |
|
13982 |
Added guideline for the use of the JNI FindClass function in event |
|
13983 |
callback functions. |
|
13984 |
</change> |
|
13985 |
<change date="15 March 2004" version="0.3.15"> |
|
13986 |
Add GetAllStackTraces and GetThreadListStackTraces. |
|
13987 |
</change> |
|
13988 |
<change date="19 March 2004" version="0.3.16"> |
|
13989 |
ClassLoad and ClassPrepare events can be posted during start phase. |
|
13990 |
</change> |
|
13991 |
<change date="25 March 2004" version="0.3.17"> |
|
13992 |
Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, |
|
13993 |
GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes. |
|
13994 |
</change> |
|
13995 |
<change date="29 March 2004" version="0.3.18"> |
|
13996 |
Return the timer kind in the timer information structure. |
|
13997 |
</change> |
|
13998 |
<change date="31 March 2004" version="0.3.19"> |
|
13999 |
Spec clarifications: |
|
14000 |
JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>. |
|
14001 |
ForceGarbageCollection does not run finalizers. |
|
14002 |
The context of the specification is the Java platform. |
|
14003 |
Warn about early instrumentation. |
|
14004 |
</change> |
|
14005 |
<change date="1 April 2004" version="0.3.20"> |
|
14006 |
Refinements to the above clarifications and |
|
14007 |
Clarify that an error returned by Agent_OnLoad terminates the VM. |
|
14008 |
</change> |
|
14009 |
<change date="1 April 2004" version="0.3.21"> |
|
14010 |
Array class creation does not generate a class load event. |
|
14011 |
</change> |
|
14012 |
<change date="7 April 2004" version="0.3.22"> |
|
14013 |
Align thread state hierarchy more closely with java.lang.Thread.State. |
|
14014 |
</change> |
|
14015 |
<change date="12 April 2004" version="0.3.23"> |
|
14016 |
Clarify the documentation of thread state. |
|
14017 |
</change> |
|
14018 |
<change date="19 April 2004" version="0.3.24"> |
|
14019 |
Remove GarbageCollectionOccurred event -- can be done by agent. |
|
14020 |
</change> |
|
14021 |
<change date="22 April 2004" version="0.3.25"> |
|
14022 |
Define "command-line option". |
|
14023 |
</change> |
|
14024 |
<change date="29 April 2004" version="0.3.26"> |
|
14025 |
Describe the intended use of bytecode instrumentation. |
|
14026 |
Fix description of extension event first parameter. |
|
14027 |
</change> |
|
14028 |
<change date="30 April 2004" version="0.3.27"> |
|
14029 |
Clarification and typos. |
|
14030 |
</change> |
|
14031 |
<change date="18 May 2004" version="0.3.28"> |
|
14032 |
Remove DataDumpRequest event. |
|
14033 |
</change> |
|
14034 |
<change date="18 May 2004" version="0.3.29"> |
|
14035 |
Clarify RawMonitorWait with zero timeout. |
|
14036 |
Clarify thread state after RunAgentThread. |
|
14037 |
</change> |
|
14038 |
<change date="24 May 2004" version="0.3.30"> |
|
14039 |
Clean-up: fix bad/old links, etc. |
|
14040 |
</change> |
|
14041 |
<change date="30 May 2004" version="0.3.31"> |
|
14042 |
Clarifications including: |
|
14043 |
All character strings are modified UTF-8. |
|
14044 |
Agent thread visibiity. |
|
14045 |
Meaning of obsolete method version. |
|
14046 |
Thread invoking heap callbacks, |
|
14047 |
</change> |
|
14048 |
<change date="1 June 2004" version="1.0.32"> |
|
14049 |
Bump major.minor version numbers to "1.0". |
|
14050 |
</change> |
|
14051 |
<change date="2 June 2004" version="1.0.33"> |
|
14052 |
Clarify interaction between ForceGarbageCollection |
|
14053 |
and ObjectFree. |
|
14054 |
</change> |
|
14055 |
<change date="6 June 2004" version="1.0.34"> |
|
14056 |
Restrict AddToBootstrapClassLoaderSearch and |
|
14057 |
SetSystemProperty to the OnLoad phase only. |
|
14058 |
</change> |
|
14059 |
<change date="11 June 2004" version="1.0.35"> |
|
14060 |
Fix typo in SetTag. |
|
14061 |
</change> |
|
14062 |
<change date="18 June 2004" version="1.0.36"> |
|
14063 |
Fix trademarks. |
|
14064 |
Add missing parameter in example GetThreadState usage. |
|
14065 |
</change> |
|
14066 |
<change date="4 August 2004" version="1.0.37"> |
|
14067 |
Copyright updates. |
|
14068 |
</change> |
|
14069 |
<change date="5 November 2004" version="1.0.38"> |
|
14070 |
Add missing function table layout. |
|
14071 |
Add missing description of C++ member function format of functions. |
|
14072 |
Clarify that name in CFLH can be NULL. |
|
14073 |
Released as part of <tm>J2SE</tm> 5.0. |
|
14074 |
</change> |
|
14075 |
<change date="24 April 2005" version="1.1.47"> |
|
14076 |
Bump major.minor version numbers to "1.1". |
|
14077 |
Add ForceEarlyReturn* functions. |
|
14078 |
Add GetOwnedMonitorStackDepthInfo function. |
|
14079 |
Add GetCurrentThread function. |
|
14080 |
Add "since" version marker. |
|
14081 |
Add AddToSystemClassLoaderSearch. |
|
14082 |
Allow AddToBootstrapClassLoaderSearch be used in live phase. |
|
14083 |
Fix historic rubbish in the descriptions of the heap_object_callback |
|
14084 |
parameter of IterateOverHeap and IterateOverInstancesOfClass functions; |
|
14085 |
disallow NULL for this parameter. |
|
14086 |
Clarify, correct and make consistent: wording about current thread, |
|
14087 |
opaque frames and insufficient number of frames in PopFrame. |
|
14088 |
Consistently use "current frame" rather than "topmost". |
|
14089 |
Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* |
|
14090 |
by making them compatible with those in ForceEarlyReturn*. |
|
14091 |
Many other clarifications and wording clean ups. |
|
14092 |
</change> |
|
14093 |
<change date="25 April 2005" version="1.1.48"> |
|
14094 |
Add GetConstantPool. |
|
14095 |
Switch references to the first edition of the VM Spec, to the seconds edition. |
|
14096 |
</change> |
|
14097 |
<change date="26 April 2005" version="1.1.49"> |
|
14098 |
Clarify minor/major version order in GetConstantPool. |
|
14099 |
</change> |
|
14100 |
<change date="26 April 2005" version="1.1.50"> |
|
14101 |
Add SetNativeMethodPrefix and SetNativeMethodPrefixes. |
|
14102 |
Reassign GetOwnedMonitorStackDepthInfo to position 153. |
|
14103 |
Break out Class Loader Search in its own documentation category. |
|
14104 |
Deal with overly long lines in XML source. |
|
14105 |
</change> |
|
14106 |
<change date="29 April 2005" version="1.1.51"> |
|
14107 |
Allow agents be started in the live phase. |
|
14108 |
Added paragraph about deploying agents. |
|
14109 |
</change> |
|
14110 |
<change date="30 April 2005" version="1.1.52"> |
|
14111 |
Add specification description to SetNativeMethodPrefix(es). |
|
14112 |
Better define the conditions on GetConstantPool. |
|
14113 |
</change> |
|
14114 |
<change date="30 April 2005" version="1.1.53"> |
|
14115 |
Break out the GetClassVersionNumber function from GetConstantPool. |
|
14116 |
Clean-up the references to the VM Spec. |
|
14117 |
</change> |
|
14118 |
<change date="1 May 2005" version="1.1.54"> |
|
14119 |
Allow SetNativeMethodPrefix(es) in any phase. |
|
14120 |
Add clarifications about the impact of redefinition on GetConstantPool. |
|
14121 |
</change> |
|
14122 |
<change date="2 May 2005" version="1.1.56"> |
|
14123 |
Various clarifications to SetNativeMethodPrefix(es). |
|
14124 |
</change> |
|
14125 |
<change date="2 May 2005" version="1.1.57"> |
|
14126 |
Add missing performance warning to the method entry event. |
|
14127 |
</change> |
|
14128 |
<change date="5 May 2005" version="1.1.58"> |
|
14129 |
Remove internal JVMDI support. |
|
14130 |
</change> |
|
14131 |
<change date="8 May 2005" version="1.1.59"> |
|
14132 |
Add <functionlink id="RetransformClasses"/>. |
|
14133 |
Revamp the bytecode instrumentation documentation. |
|
14134 |
Change <functionlink id="IsMethodObsolete"/> to no longer |
|
14135 |
require the can_redefine_classes capability. |
|
14136 |
</change> |
|
14137 |
<change date="11 May 2005" version="1.1.63"> |
|
14138 |
Clarifications for retransformation. |
|
14139 |
</change> |
|
14140 |
<change date="11 May 2005" version="1.1.64"> |
|
14141 |
Clarifications for retransformation, per review. |
|
14142 |
Lock "retransformation (in)capable" at class load enable time. |
|
14143 |
</change> |
|
14144 |
<change date="4 June 2005" version="1.1.67"> |
|
14145 |
Add new heap functionity which supports reporting primitive values, |
|
14146 |
allows setting the referrer tag, and has more powerful filtering: |
|
14147 |
FollowReferences, IterateThroughHeap, and their associated |
|
14148 |
callbacks, structs, enums, and constants. |
|
14149 |
</change> |
|
14150 |
<change date="4 June 2005" version="1.1.68"> |
|
14151 |
Clarification. |
|
14152 |
</change> |
|
14153 |
<change date="6 June 2005" version="1.1.69"> |
|
14154 |
FollowReferences, IterateThroughHeap: Put callbacks in a struct; |
|
14155 |
Add missing error codes; reduce bits in the visit control flags. |
|
14156 |
</change> |
|
14157 |
<change date="14 June 2005" version="1.1.70"> |
|
14158 |
More on new heap functionity: spec clean-up per review. |
|
14159 |
</change> |
|
14160 |
<change date="15 June 2005" version="1.1.71"> |
|
14161 |
More on new heap functionity: Rename old heap section to Heap (1.0). |
|
14162 |
</change> |
|
14163 |
<change date="21 June 2005" version="1.1.72"> |
|
14164 |
Fix typos. |
|
14165 |
</change> |
|
14166 |
<change date="27 June 2005" version="1.1.73"> |
|
14167 |
Make referrer info structure a union. |
|
14168 |
</change> |
|
14169 |
<change date="9 September 2005" version="1.1.74"> |
|
14170 |
In new heap functions: |
|
14171 |
Add missing superclass reference kind. |
|
14172 |
Use a single scheme for computing field indexes. |
|
14173 |
Remove outdated references to struct based referrer info. |
|
14174 |
</change> |
|
14175 |
<change date="12 September 2005" version="1.1.75"> |
|
14176 |
Don't callback during FollowReferences on frivolous java.lang.Object superclass. |
|
14177 |
</change> |
|
14178 |
<change date="13 September 2005" version="1.1.76"> |
|
14179 |
In string primitive callback, length now Unicode length. |
|
14180 |
In array and string primitive callbacks, value now "const". |
|
14181 |
Note possible compiler impacts on setting JNI function table. |
|
14182 |
</change> |
|
14183 |
<change date="13 September 2005" version="1.1.77"> |
|
14184 |
GetClassVersionNumbers() and GetConstantPool() should return |
|
14185 |
error on array or primitive class. |
|
14186 |
</change> |
|
14187 |
<change date="14 September 2005" version="1.1.78"> |
|
14188 |
Grammar fixes. |
|
14189 |
</change> |
|
14190 |
<change date="26 September 2005" version="1.1.79"> |
|
14191 |
Add IsModifiableClass query. |
|
14192 |
</change> |
|
14193 |
<change date="9 February 2006" version="1.1.81"> |
|
14194 |
Add referrer_class_tag parameter to jvmtiHeapReferenceCallback. |
|
14195 |
</change> |
|
14196 |
<change date="13 February 2006" version="1.1.82"> |
|
14197 |
Doc fixes: update can_redefine_any_class to include retransform. |
|
14198 |
Clarify that exception events cover all Throwables. |
|
14199 |
In GetStackTrace, no test is done for start_depth too big if start_depth is zero, |
|
14200 |
Clarify fields reported in Primitive Field Callback -- static vs instance. |
|
14201 |
Repair confusing names of heap types, including callback names. |
|
14202 |
Require consistent usage of stack depth in the face of thread launch methods. |
|
14203 |
Note incompatibility of <jvmti/> memory management with other systems. |
|
14204 |
</change> |
|
14205 |
<change date="14 February 2006" version="1.1.85"> |
|
14206 |
Fix typos and missing renames. |
|
14207 |
</change> |
|
14208 |
<change date="13 March 2006" version="1.1.86"> |
|
14209 |
Clarify that jmethodIDs and jfieldIDs can be saved. |
|
14210 |
Clarify that Iterate Over Instances Of Class includes subclasses. |
|
14211 |
</change> |
|
14212 |
<change date="14 March 2006" version="1.1.87"> |
|
14213 |
Better phrasing. |
|
14214 |
</change> |
|
14215 |
<change date="16 March 2006" version="1.1.88"> |
|
14216 |
Match the referrer_index for static fields in Object Reference Callback |
|
14217 |
with the Reference Implementation (and all other known implementations); |
|
14218 |
that is, make it match the definition for instance fields. |
|
14219 |
In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover |
|
14220 |
an invalid thread in the list; and specify that not started threads |
|
14221 |
return empty stacks. |
|
14222 |
</change> |
|
14223 |
<change date="17 March 2006" version="1.1.89"> |
|
14224 |
Typo. |
|
14225 |
</change> |
|
14226 |
<change date="25 March 2006" version="1.1.90"> |
|
14227 |
Typo. |
|
14228 |
</change> |
|
14229 |
<change date="6 April 2006" version="1.1.91"> |
|
14230 |
Remove restrictions on AddToBootstrapClassLoaderSearch and |
|
14231 |
AddToSystemClassLoaderSearch. |
|
14232 |
</change> |
|
14233 |
<change date="1 May 2006" version="1.1.93"> |
|
14234 |
Changed spec to return -1 for monitor stack depth for the |
|
14235 |
implementation which can not determine stack depth. |
|
14236 |
</change> |
|
14237 |
<change date="3 May 2006" version="1.1.94"> |
|
14238 |
Corrections for readability and accuracy courtesy of Alan Pratt of IBM. |
|
14239 |
List the object relationships reported in FollowReferences. |
|
14240 |
</change> |
|
14241 |
<change date="5 May 2006" version="1.1.95"> |
|
14242 |
Clarify the object relationships reported in FollowReferences. |
|
14243 |
</change> |
|
14244 |
<change date="28 June 2006" version="1.1.98"> |
|
14245 |
Clarify DisposeEnvironment; add warning. |
|
14246 |
Fix typos in SetLocalXXX "retrieve" => "set". |
|
14247 |
Clarify that native method prefixes must remain set while used. |
|
14248 |
Clarify that exactly one Agent_OnXXX is called per agent. |
|
14249 |
Clarify that library loading is independent from start-up. |
|
14250 |
Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec. |
|
14251 |
</change> |
|
14252 |
<change date="31 July 2006" version="1.1.99"> |
|
14253 |
Clarify the interaction between functions and exceptions. |
|
14254 |
Clarify and give examples of field indices. |
|
14255 |
Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. |
|
14256 |
Update links to point to Java 6. |
|
14257 |
</change> |
|
14258 |
<change date="6 August 2006" version="1.1.102"> |
|
14259 |
Add ResourceExhaustedEvent. |
|
14260 |
</change> |
|
14287 | 14261 |
<change date="11 October 2012" version="1.2.2"> |
14262 |
Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. |
|
14263 |
</change> |
|
1 | 14264 |
</changehistory> |
14265 |
||
14266 |
</specification> |
|
14267 |
<!-- Keep this comment at the end of the file |
|
14268 |
Local variables: |
|
14269 |
mode: sgml |
|
14270 |
sgml-omittag:t |
|
14271 |
sgml-shorttag:t |
|
14272 |
sgml-namecase-general:t |
|
14273 |
sgml-general-insert-case:lower |
|
14274 |
sgml-minimize-attributes:nil |
|
14275 |
sgml-always-quote-attributes:t |
|
14276 |
sgml-indent-step:2 |
|
14277 |
sgml-indent-data:t |
|
14278 |
sgml-parent-document:nil |
|
14279 |
sgml-exposed-tags:nil |
|
14280 |
sgml-local-catalogs:nil |
|
14281 |
sgml-local-ecat-files:nil |
|
14282 |
End: |
|
14283 |
--> |