1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
3 <!--
4 Copyright (c) 2002, 2022, Oracle and/or its affiliates. All rights reserved.
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6
7 This code is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License version 2 only, as
9 published by the Free Software Foundation.
10
11 This code is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 version 2 for more details (a copy is included in the LICENSE file that
15 accompanied this code).
16
17 You should have received a copy of the GNU General Public License version
18 2 along with this work; if not, write to the Free Software Foundation,
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 or visit www.oracle.com if you need additional information or have any
23 questions.
24 -->
25
26 <!DOCTYPE specification [
27 <!ELEMENT specification (title, intro*, functionsection, errorsection,
28 eventsection, datasection, issuessection, changehistory)>
29 <!ATTLIST specification label CDATA #REQUIRED>
30
31 <!ELEMENT title (#PCDATA|jvmti|tm)*>
32 <!ATTLIST title subtitle CDATA #REQUIRED>
33
34 <!ELEMENT intro ANY>
35 <!ATTLIST intro id CDATA #IMPLIED
36 label CDATA "">
37
38 <!ELEMENT functionsection (intro*, category*)>
39 <!ATTLIST functionsection label CDATA #REQUIRED>
40
41 <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*,
42 (function|callback|elide)*)>
43 <!ATTLIST category id CDATA #REQUIRED
44 label CDATA #REQUIRED>
45
46 <!ELEMENT function (synopsis, typedef*, description?, origin,
47 (capabilities|eventcapabilities),
48 parameters, errors)>
49 <!ATTLIST function id CDATA #REQUIRED
50 num CDATA #REQUIRED
51 phase (onload|onloadOnly|start|live|any) #IMPLIED
52 callbacksafe (safe|unsafe) #IMPLIED
53 impl CDATA #IMPLIED
54 hide CDATA #IMPLIED
55 jkernel (yes|no) #IMPLIED
56 since CDATA "1.0">
57
58 <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
59 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
60 synopsis, description?, parameters)>
61 <!ATTLIST callback id CDATA #REQUIRED
62 since CDATA "1.0">
63
64 <!ELEMENT synopsis (#PCDATA|jvmti)*>
65
66 <!ELEMENT typedef (description?, field*)>
67 <!ATTLIST typedef id CDATA #REQUIRED
68 label CDATA #REQUIRED
69 since CDATA "1.0">
70
71 <!ELEMENT uniontypedef (description?, field*)>
72 <!ATTLIST uniontypedef id CDATA #REQUIRED
73 label CDATA #REQUIRED
74 since CDATA "1.0">
75
76 <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
77 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct),
78 description)>
79 <!ATTLIST field id CDATA #REQUIRED>
80
81 <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
82 <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
83 label CDATA #REQUIRED>
84
85 <!ELEMENT capabilityfield (description)>
86 <!ATTLIST capabilityfield id CDATA #REQUIRED
87 disp1 CDATA ""
88 disp2 CDATA ""
89 since CDATA "1.0">
90
91 <!ELEMENT description ANY>
92
93 <!ELEMENT capabilities (required*, capability*)>
94
95 <!ELEMENT eventcapabilities EMPTY>
96
97 <!ELEMENT required ANY>
98 <!ATTLIST required id CDATA #REQUIRED>
99
100 <!ELEMENT capability ANY>
101 <!ATTLIST capability id CDATA #REQUIRED>
102
103 <!ELEMENT parameters (param*)>
104
105 <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
106 jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
107 outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf),
108 description)>
109 <!ATTLIST param id CDATA #REQUIRED>
110
111 <!ELEMENT jmethodID EMPTY>
112 <!ATTLIST jmethodID class CDATA #IMPLIED
113 native CDATA #IMPLIED>
114
115 <!ELEMENT jfieldID EMPTY>
116 <!ATTLIST jfieldID class CDATA #IMPLIED>
117
118 <!ELEMENT jclass EMPTY>
119 <!ATTLIST jclass method CDATA #IMPLIED
120 field CDATA #IMPLIED>
121
122 <!ELEMENT jframeID EMPTY>
123 <!ATTLIST jframeID thread CDATA #IMPLIED>
124
125 <!ELEMENT jrawMonitorID EMPTY>
126
127 <!ELEMENT jthread EMPTY>
128 <!ATTLIST jthread started CDATA #IMPLIED
129 null CDATA #IMPLIED
130 frame CDATA #IMPLIED
131 impl CDATA #IMPLIED>
132
133 <!ELEMENT varargs EMPTY>
134
135 <!ELEMENT jthreadGroup EMPTY>
136 <!ELEMENT jobject EMPTY>
137 <!ATTLIST jobject frame CDATA #IMPLIED>
138
139 <!ELEMENT jvalue EMPTY>
140 <!ELEMENT jchar EMPTY>
141 <!ELEMENT jint EMPTY>
142 <!ATTLIST jint min CDATA #IMPLIED>
143 <!ELEMENT jlong EMPTY>
144 <!ELEMENT jfloat EMPTY>
145 <!ELEMENT jdouble EMPTY>
146 <!ELEMENT jlocation EMPTY>
147 <!ELEMENT jboolean EMPTY>
148 <!ELEMENT char EMPTY>
149 <!ELEMENT uchar EMPTY>
150 <!ELEMENT size_t EMPTY>
151 <!ELEMENT void EMPTY>
152 <!ELEMENT enum (#PCDATA)*>
153 <!ELEMENT struct (#PCDATA)*>
154
155 <!ELEMENT nullok ANY>
156
157 <!ELEMENT ptrtype ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
158 jthreadGroup|jobject|jvalue), nullok?)>
159
160 <!ELEMENT outptr ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
161 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
162 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
163 <!ATTLIST outptr impl CDATA #IMPLIED>
164
165 <!ELEMENT allocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
166 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
167 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
168 <!ATTLIST allocbuf incount CDATA #IMPLIED
169 outcount CDATA #IMPLIED>
170
171 <!ELEMENT allocallocbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
172 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
173 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
174 <!ATTLIST allocallocbuf incount CDATA #IMPLIED
175 outcount CDATA #IMPLIED>
176
177 <!ELEMENT inptr (struct, nullok?)>
178
179 <!ELEMENT inbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
180 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
181 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
182 <!ATTLIST inbuf incount CDATA #IMPLIED>
183
184 <!ELEMENT outbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
185 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
186 jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
187 <!ATTLIST outbuf incount CDATA #IMPLIED
188 outcount CDATA #IMPLIED>
189
190 <!ELEMENT vmbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
191 jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
192 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
193 <!ATTLIST vmbuf incount CDATA #IMPLIED
194 outcount CDATA #IMPLIED>
195
196 <!ELEMENT agentbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
197 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
198 jlocation|jboolean|char|uchar|size_t|void), nullok?)>
199 <!ATTLIST agentbuf incount CDATA #IMPLIED
200 outcount CDATA #IMPLIED>
201
202 <!ELEMENT allocfieldbuf ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
203 jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
204 jlocation|jboolean|char|uchar|size_t|void))>
205 <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
206
207 <!ELEMENT errors (error*)>
208
209 <!ELEMENT error ANY>
210 <!ATTLIST error id CDATA #REQUIRED>
211
212 <!ELEMENT errorsection (intro*, errorcategory*)>
213 <!ATTLIST errorsection label CDATA #REQUIRED>
214
215 <!ELEMENT errorcategory (intro*, errorid*)>
216 <!ATTLIST errorcategory id CDATA #REQUIRED
217 label CDATA #REQUIRED>
218
219 <!ELEMENT errorid ANY>
220 <!ATTLIST errorid id CDATA #REQUIRED
221 num CDATA #REQUIRED>
222
223 <!ELEMENT datasection (intro*, basetypes*)>
224
225 <!ELEMENT basetypes (intro*, basetype*)>
226 <!ATTLIST basetypes id CDATA #REQUIRED
227 label CDATA #REQUIRED>
228
229 <!ELEMENT basetype (definition?,description)>
230 <!ATTLIST basetype id CDATA #REQUIRED
231 name CDATA #IMPLIED>
232
233 <!ELEMENT definition (#PCDATA|jvmti)*>
234
235 <!ELEMENT eventsection (intro*, (event|elide)*)>
236 <!ATTLIST eventsection label CDATA #REQUIRED>
237
238 <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
239 <!ATTLIST event id CDATA #REQUIRED
240 label CDATA #REQUIRED
241 const CDATA #REQUIRED
242 num CDATA #REQUIRED
243 phase (onload|start|live|any) #IMPLIED
244 filtered (thread|global) #IMPLIED
245 since CDATA "1.0">
246
247 <!ELEMENT issuessection (intro*)>
248 <!ATTLIST issuessection label CDATA #REQUIRED>
249
250 <!ELEMENT changehistory (intro*, change*)>
251 <!ATTLIST changehistory update CDATA #REQUIRED
252 id CDATA #REQUIRED>
253
254 <!ELEMENT change ANY>
255 <!ATTLIST change date CDATA #REQUIRED
256 version CDATA #IMPLIED>
257
258 <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
259 <!ATTLIST functionlink id CDATA #REQUIRED>
260
261 <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
262 <!ATTLIST datalink id CDATA #REQUIRED>
263
264 <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
265 <!ATTLIST typelink id CDATA #REQUIRED>
266
267 <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
268 <!ATTLIST fieldlink id CDATA #REQUIRED
269 struct CDATA #REQUIRED>
270
271 <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
272 <!ATTLIST paramlink id CDATA #REQUIRED>
273
274 <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
275 <!ATTLIST eventlink id CDATA #REQUIRED>
276
277 <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
278 <!ATTLIST errorlink id CDATA #REQUIRED>
279
280 <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
281 <!ATTLIST externallink id CDATA #REQUIRED>
282
283 <!ELEMENT vmspec EMPTY>
284 <!ATTLIST vmspec chapter CDATA #IMPLIED>
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 blockquote ANY>
337
338 <!ELEMENT dl (dt|dd)+>
339
340 <!ELEMENT dd ANY>
341
342 <!ELEMENT dt (#PCDATA|jvmti|code|i|b)*>
343
344 <!ELEMENT table (tr)+>
345
346 <!ELEMENT tr (td|th)*>
347 <!ATTLIST tr class CDATA #IMPLIED>
348
349 <!ELEMENT td ANY>
350 <!ATTLIST td class CDATA #IMPLIED>
351
352 <!ELEMENT th ANY>
353 <!ATTLIST th class CDATA #IMPLIED
354 scope (col|row) #IMPLIED>
355
356 <!ELEMENT ul (li)+>
357 <!ATTLIST ul type (disc|circle|square) "disc">
358
359 <!ELEMENT li ANY>
360 ]>
361
362 <specification label="JVM(TM) Tool Interface">
363 <title subtitle="Version">
364 <tm>JVM</tm> Tool Interface
365 </title>
366
367 <intro id="whatIs" label="What is the JVM Tool Interface?">
368 The <tm>JVM</tm> Tool Interface (<jvmti/>)
369 is a programming interface used by development and monitoring tools.
370 It provides both a way to inspect the state and
371 to control the execution of applications running in the
372 <tm>Java</tm> virtual machine (VM).
373 <p/>
374 <jvmti/> is intended to provide a VM interface for the full breadth of tools
375 that need access to VM state, including but not limited to: profiling,
376 debugging, monitoring, thread analysis, and coverage analysis tools.
377 <p/>
378 <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
379 machine.
380 <p/>
381 <jvmti/> is a two-way interface.
382 A client of <jvmti/>, hereafter called an <i>agent</i>,
383 can be notified of
384 interesting occurrences through <internallink id="EventSection">events</internallink>.
385 <jvmti/>
386 can query and control the application through many
387 <internallink id="FunctionSection">functions</internallink>,
388 either in response to events or
389 independent of them.
390 <p/>
391 Agents run in the same process with and communicate directly with
392 the virtual machine executing
393 the application being examined. This communication is
394 through a native interface (<jvmti/>). The native in-process interface allows
395 maximal control with minimal intrusion on the part of a tool.
396 Typically, agents are relatively compact. They can be controlled
397 by a separate process which implements the bulk of a tool's
398 function without interfering with the target application's normal execution.
399 </intro>
400
401 <intro id="architecture" label="Architecture">
402 Tools can be written directly to <jvmti/> or indirectly
403 through higher level interfaces.
404 The Java Platform Debugger Architecture includes <jvmti/>, but also
405 contains higher-level, out-of-process debugger interfaces. The higher-level
406 interfaces are more appropriate than <jvmti/> for many tools.
407 For more information on the Java Platform Debugger Architecture,
408 see the
409 <externallink id="jpda/architecture.html">Java
410 Platform Debugger Architecture website</externallink>.
411 </intro>
412
413 <intro id="writingAgents" label="Writing Agents">
414 Agents can be written in any native language that supports C
415 language calling conventions and C or C++
416 definitions.
417 <p/>
418 The function, event, data type, and constant definitions needed for
419 using <jvmti/> are defined in the include file <code>jvmti.h</code>.
420 To use these definitions add the <tm>J2SE</tm> include directory
421 to your include path and add
422 <example>
423 #include <jvmti.h>
424 </example>
425 to your source code.
426 </intro>
427
428 <intro id="deployingAgents" label="Deploying Agents">
429 An agent is deployed in a platform specific manner but is typically the
430 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
431 system, for example, an agent library is a "Dynamic Linked Library" (DLL).
432 On <tm>Linux</tm> Operating Environment, an agent library is a shared object
433 (<code>.so</code> file).
434 <p/>
435
436 An agent may be started at VM startup by specifying the agent library
437 name using a <internallink id="starting">command line option</internallink>.
438 Some implementations may support a mechanism to <internallink id="onattach">
439 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
440 The details of how this is initiated are implementation specific.
441 </intro>
442
443 <intro id="entryPoint" label="Statically Linked Agents (since version 1.2.3)">
444
445 A native JVMTI Agent may be <i>statically linked</i> with the VM.
446 The manner in which the library and VM image are combined is
447 implementation-dependent.
448 An agent L whose image has been combined with the VM is defined as
449 <i>statically linked</i> if and only if the agent exports a function
450 called Agent_OnLoad_L.
451 <p/>
452 If a <i>statically linked</i> agent L exports a function called
453 Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
454 function will be ignored.
455 If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
456 function will be invoked with the same arguments and expected return
457 value as specified for the Agent_OnLoad function.
458 An agent L that is <i>statically linked</i> will prohibit an agent of
459 the same name from being loaded dynamically.
460 <p/>
461 The VM will invoke the Agent_OnUnload_L function of the agent, if such
462 a function is exported, at the same point during VM execution as it would
463 have called the dynamic entry point Agent_OnUnLoad. A statically loaded
464 agent cannot be unloaded. The Agent_OnUnload_L function will still be
465 called to do any other agent shutdown related tasks.
466 If a <i>statically linked</i> agent L exports a function called
467 Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
468 function will be ignored.
469 <p/>
470 If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
471 will be invoked with the same arguments and expected return value as
472 specified for the Agent_OnAttach function.
473 If a <i>statically linked</i> agent L exports a function called
474 Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
475 function will be ignored.
476 </intro>
477
478 <intro id="starting" label="Agent Command Line Options">
479 The term "command-line option" is used below to
480 mean options supplied in the <code>JavaVMInitArgs</code> argument
481 to the <code>JNI_CreateJavaVM</code> function of the JNI
482 Invocation API.
483 <p/>
484 One of the two following
485 command-line options is used on VM startup to
486 properly load and run agents.
487 These arguments identify the library containing
488 the agent as well as an options
489 string to be passed in at startup.
490 <dl>
491 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt>
492 <dd>
493 The name following <code>-agentlib:</code> is the name of the
494 library to load. Lookup of the library, both its full name and location,
495 proceeds in a platform-specific manner.
496 Typically, the <i><agent-lib-name></i> is expanded to an
497 operating system specific file name.
498 The <i><options></i> will be passed to the agent on start-up.
499 For example, if the option
500 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
501 load the shared library <code>foo.dll</code> from the system <code>PATH</code>
502 under <tm>Windows</tm> or <code>libfoo.so</code> from the
503 <code>LD_LIBRARY_PATH</code> under <tm>Linux</tm>.
504 If the agent library is statically linked into the executable
505 then no actual loading takes place.
506 <p/>
507 </dd>
508 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt>
509 <dd>
510 The path following <code>-agentpath:</code> is the absolute path from which
511 to load the library.
512 No library name expansion will occur.
513 The <i><options></i> will be passed to the agent on start-up.
514 For example, if the option
515 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
516 load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
517 library is statically linked into the executable
518 then no actual loading takes place.
519 <p/>
520 </dd>
521 </dl>
522 For a dynamic shared library agent, the start-up routine
523 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
524 in the library will be invoked. If the agent library is statically linked
525 into the executable then the system will attempt to invoke the
526 <code>Agent_OnLoad_<agent-lib-name></code> entry point where
527 <agent-lib-name> is the basename of the
528 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
529 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
530 <p/>
531 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
532 will be searched for JNI native method implementations to facilitate the
533 use of Java programming language code in tools, as is needed for
534 <internallink id="bci">bytecode instrumentation</internallink>.
535 <p/>
536 The agent libraries will be searched after all other libraries have been
537 searched (agents wishing to override or intercept the native method
538 implementations of non-agent methods can use the
539 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
540 <p/>
541 These switches do the above and nothing more - they do not change the
542 state of the VM or <jvmti/>. No command line options are needed
543 to enable <jvmti/>
544 or aspects of <jvmti/>, this is handled programmatically
545 by the use of
546 <internallink id="capability">capabilities</internallink>.
547 </intro>
548
549 <intro id="startup" label="Agent Start-Up">
550 The VM starts each agent by invoking a start-up function.
551 If the agent is started in the <code>OnLoad</code>
552 <functionlink id="GetPhase">phase</functionlink> the function
553 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
554 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
555 for statically linked agents will be invoked.
556 If the agent is started in the live
557 <functionlink id="GetPhase">phase</functionlink> the function
558 <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
559 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
560 for statically linked agents will be invoked.
561 Exactly one call to a start-up function is made per agent.
562 </intro>
563
564 <intro id="onload" label="Agent Start-Up (OnLoad phase)">
565 If an agent is started during the <code>OnLoad</code> phase then its
566 agent library must export a start-up function with the following prototype:
567 <example>
568 JNIEXPORT jint JNICALL
569 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
570 Or for a statically linked agent named 'L':
571 <example>
572 JNIEXPORT jint JNICALL
573 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
574
575 The VM will start the agent by calling this function.
576 It will be called early enough in VM initialization that:
577 <ul>
578 <li><functionlink id="SetSystemProperty">system properties</functionlink>
579 may be set before they have been used in the start-up of the VM</li>
580 <li>the full set of
581 <internallink id="capability">capabilities</internallink>
582 is still available (note that capabilities that configure the VM
583 may only be available at this time--see the
584 <internallink id="capability">Capability function section</internallink>)</li>
585 <li>no bytecodes have executed</li>
586 <li>no classes have been loaded</li>
587 <li>no objects have been created</li>
588 </ul>
589 <p/>
590 The VM will call the <code>Agent_OnLoad</code> or
591 <code>Agent_OnLoad_<agent-lib-name></code> function with
592 <i><options></i> as the second argument -
593 that is, using the command-line option examples,
594 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
595 argument of <code>Agent_OnLoad</code>.
596 The <code>options</code> argument is encoded as a
597 <internallink id="mUTF">modified UTF-8</internallink> string.
598 If <i>=<options></i> is not specified,
599 a zero length string is passed to <code>options</code>.
600 The lifespan of the <code>options</code> string is the
601 <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code>
602 call. If needed beyond this time the string or parts of the string must
603 be copied.
604 The period between when <code>Agent_OnLoad</code> is called and when it
605 returns is called the <i>OnLoad phase</i>.
606 Since the VM is not initialized during the OnLoad
607 <functionlink id="GetPhase">phase</functionlink>,
608 the set of allowed operations
609 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
610 functionality available at this time).
611 The agent can safely process the options and set
612 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
613 the VM initialization event is received
614 (that is, the <eventlink id="VMInit">VMInit</eventlink>
615 callback is invoked), the agent
616 can complete its initialization.
617 <rationale>
618 Early startup is required so that agents can set the desired capabilities,
619 many of which must be set before the VM is initialized.
620 In JVMDI, the -Xdebug command-line option provided
621 very coarse-grain control of capabilities.
622 JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
623 No reasonable command-line
624 option could provide the fine-grain of control required to balance needed capabilities vs
625 performance impact.
626 Early startup is also needed so that agents can control the execution
627 environment - modifying the file system and system properties to install
628 their functionality.
629 </rationale>
630 <p/>
631 The return value from <code>Agent_OnLoad</code> or
632 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error.
633 Any value other than zero indicates an error and causes termination of the VM.
634 </intro>
635
636 <intro id="onattach" label="Agent Start-Up (Live phase)">
637 A VM may support a mechanism that allows agents to be started in the VM during the live
638 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
639 are implementation specific. For example, a tool may use some platform specific mechanism,
640 or implementation specific API, to attach to the running VM, and request it start a given
641 agent.
642 <p/>
643 If an agent is started during the live phase then its agent library
644 must export a start-up function
645 with the following prototype:
646 <example>
647 JNIEXPORT jint JNICALL
648 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
649 Or for a statically linked agent named 'L':
650 <example>
651 JNIEXPORT jint JNICALL
652 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
653
654 <p/>
655 The VM will start the agent by calling this function.
656 It will be called in the context of a thread
657 that is attached to the VM. The first argument <i><vm></i> is the Java VM.
658 The <i><options></i> argument is the startup options provided to the agent.
659 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8
660 </internallink> string.
661 If startup options were not provided, a zero length string is passed to
662 <code>options</code>. The lifespan of the <code>options</code> string is the
663 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call.
664 If needed beyond this time the string or parts of the string must be copied.
665 <p/>
666 Note that some <internallink id="capability">capabilities</internallink>
667 may not be available in the live phase.
668 <p/>
669 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name
670 ></code> function initializes the agent and returns a value
671 to the VM to indicate if an error occurred. Any value other than zero indicates an error.
672 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
673 some implementation specific action -- for example it might print an error to standard error,
674 or record the error in a system log.
675 </intro>
676
677 <intro id="onunload" label="Agent Shutdown">
678 The library may optionally export a
679 shutdown function with the following prototype:
680 <example>
681 JNIEXPORT void JNICALL
682 Agent_OnUnload(JavaVM *vm)</example>
683 Or for a statically linked agent named 'L':
684 <example>
685 JNIEXPORT void JNICALL
686 Agent_OnUnload_L(JavaVM *vm)</example>
687
688 This function will be called by the VM when the library is about to be unloaded.
689 The library will be unloaded (unless it is statically linked into the
690 executable) and this function will be called if some platform specific
691 mechanism causes the unload (an unload mechanism is not specified in this document)
692 or the library is (in effect) unloaded by the termination of the VM.
693 VM termination includes normal termination and VM failure, including start-up failure,
694 but not, of course, uncontrolled shutdown. An implementation may also
695 choose to not call this function if the <code>Agent_OnAttach</code>/
696 <code>Agent_OnAttach_L</code> function reported an error (returned a non-zero value).
697 Note the distinction between this function and the
698 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
699 to be sent, the VM must have run at least to the point of initialization and a valid
700 <jvmti/> environment must exist which has set a callback for VMDeath
701 and enabled the event.
702 None of these are required for <code>Agent_OnUnload</code> or
703 <code>Agent_OnUnload_<agent-lib-name></code> and this function
704 is also called if the library is unloaded for other reasons.
705 In the case that a VM Death event is sent, it will be sent before this
706 function is called (assuming this function is called due to VM termination).
707 This function can be used to clean-up resources allocated by the agent.
708 </intro>
709
710 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
711 Since the command-line cannot always be accessed or modified, for example in embedded VMs
712 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
713 provided so that agents may be launched in these cases.
714 <p/>
715 Platforms which support environment variables or other named strings, may support the
716 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space
717 boundaries. White-space characters include space, tab, carriage-return, new-line,
718 vertical-tab, and form-feed. Sequences of white-space characters are considered
719 equivalent to a single white-space character. No white-space is included in the options
720 unless quoted. Quoting is as follows:
721 <ul>
722 <li>All characters enclosed between a pair of single quote marks (''), except a single
723 quote, are quoted.</li>
724 <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
725 <li>All characters enclosed between a pair of double quote marks (""), except a double
726 quote, are quoted.</li>
727 <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
728 <li>A quoted part can start or end anywhere in the variable.</li>
729 <li>White-space characters have no special meaning when quoted -- they are included in
730 the option like any other character and do not mark white-space boundaries.</li>
731 <li>The pair of quote marks is not included in the option.</li>
732 </ul>
733 <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied
734 in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is
735 a concern; for example, the Reference Implementation disables this feature on Unix systems when
736 the effective user or group ID differs from the real ID.
737 This feature is intended to support the initialization of tools -- specifically including the
738 launching of native or Java programming language agents. Multiple tools may wish to use this
739 feature, so the variable should not be overwritten, instead, options should be appended to
740 the variable. Note that since the variable is processed at the time of the JNI Invocation
741 API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
742 </intro>
743
744 <intro id="environments" label="Environments">
745 The <jvmti/> specification supports the use of multiple simultaneous
746 <jvmti/> agents.
747 Each agent has its own <jvmti/> environment.
748 That is, the <jvmti/> state is
749 separate for each agent - changes to one environment do not affect the
750 others. The state of a <jvmti/>
751 environment includes:
752 <ul>
753 <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
754 <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
755 <li><internallink id="capability">the capabilities</internallink></li>
756 <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
757 </ul>
758 Although their <jvmti/> state
759 is separate, agents inspect and modify the shared state
760 of the VM, they also share the native environment in which they execute.
761 As such, an agent can perturb the results of other agents or cause them
762 to fail. It is the responsibility of the agent writer to specify the level
763 of compatibility with other agents. <jvmti/> implementations are not capable
764 of preventing destructive interactions between agents. Techniques to reduce
765 the likelihood of these occurrences are beyond the scope of this document.
766 <p/>
767 An agent creates a <jvmti/> environment
768 by passing a <jvmti/> version
769 as the interface ID to the JNI Invocation API function
770 <externallink id="jni/invocation.html#getenv">
771 <code>GetEnv</code></externallink>.
772 See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
773 for more details on the creation and use of
774 <jvmti/> environments.
775 Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from
776 <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
777 </intro>
778
779 <intro id="bci" label="Bytecode Instrumentation">
780 This interface does not include some events that one might expect in an interface with
781 profiling support. Some examples include full speed
782 method enter and exit events. The interface instead provides support for
783 <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
784 bytecode instructions which comprise the target program. Typically, these alterations
785 are to add "events" to the code of a method - for example, to add, at the beginning of a method,
786 a call to <code>MyProfiler.methodEntered()</code>.
787 Since the changes are purely additive, they do not modify application
788 state or behavior.
789 Because the inserted agent code is standard bytecodes, the VM can run at full speed,
790 optimizing not only the target program but also the instrumentation. If the
791 instrumentation does not involve switching from bytecode execution, no expensive
792 state transitions are needed. The result is high performance events.
793 This approach also provides complete control to the agent: instrumentation can be
794 restricted to "interesting" portions of the code (e.g., the end user's code) and
795 can be conditional. Instrumentation can run entirely in Java programming language
796 code or can call into the native agent. Instrumentation can simply maintain
797 counters or can statistically sample events.
798 <p/>
799 Instrumentation can be inserted in one of three ways:
800 <ul>
801 <li>
802 Static Instrumentation: The class file is instrumented before it
803 is loaded into the VM - for example, by creating a duplicate directory of
804 <code>*.class</code> files which have been modified to add the instrumentation.
805 This method is extremely awkward and, in general, an agent cannot know
806 the origin of the class files which will be loaded.
807 </li>
808 <li>
809 Load-Time Instrumentation: When a class file is loaded by the VM, the raw
810 bytes of the class file are sent for instrumentation to the agent.
811 The <eventlink id="ClassFileLoadHook"/>
812 event, triggered by the class load,
813 provides this functionality. This mechanism provides efficient
814 and complete access to one-time instrumentation.
815 </li>
816 <li>
817 Dynamic Instrumentation: A class which is already loaded (and possibly
818 even running) is modified. This optional feature is provided by the
819 <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
820 <functionlink id="RetransformClasses"/> function.
821 Classes can be modified multiple times and can be returned to their
822 original state.
823 The mechanism allows instrumentation which changes during the
824 course of execution.
825 </li>
826 </ul>
827 <p/>
828 The class modification functionality provided in this interface
829 is intended to provide a mechanism for instrumentation
830 (the <eventlink id="ClassFileLoadHook"/> event
831 and the <functionlink id="RetransformClasses"/> function)
832 and, during development, for fix-and-continue debugging
833 (the <functionlink id="RedefineClasses"/> function).
834 <p/>
835 Care must be taken to avoid perturbing dependencies, especially when
836 instrumenting core classes. For example, an approach to getting notification
837 of every object allocation is to instrument the constructor on
838 <code>Object</code>. Assuming that the constructor is initially
839 empty, the constructor could be changed to:
840 <example>
841 public Object() {
842 MyProfiler.allocationTracker(this);
843 }
844 </example>
845 However, if this change was made using the
846 <eventlink id="ClassFileLoadHook"/>
847 event then this might impact a typical VM as follows:
848 the first created object will call the constructor causing a class load of
849 <code>MyProfiler</code>; which will then cause
850 object creation, and since <code>MyProfiler</code> isn't loaded yet,
851 infinite recursion; resulting in a stack overflow. A refinement of this
852 would be to delay invoking the tracking method until a safe time. For
853 example, <code>trackAllocations</code> could be set in the
854 handler for the <code>VMInit</code> event.
855 <example>
856 static boolean trackAllocations = false;
857
858 public Object() {
859 if (trackAllocations) {
860 MyProfiler.allocationTracker(this);
861 }
862 }
863 </example>
864 <p/>
865 The <functionlink id="SetNativeMethodPrefix"/> allows native methods
866 to be instrumented by the use of wrapper methods.
867 </intro>
868
869 <intro id="bcimodules" label="Bytecode Instrumentation of code in modules">
870 Agents can use the functions <functionlink id="AddModuleReads"/>,
871 <functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>,
872 <functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/>
873 to update a module to expand the set of modules that it reads, the set of
874 packages that it exports or opens to other modules, or the services that it
875 uses and provides.
876 <p/>
877 As an aid to agents that deploy supporting classes on the search path of
878 the bootstrap class loader, or the search path of the class loader that
879 loads the main class, the Java virtual machine arranges for the module
880 of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
881 read the unnamed module of both class loaders.
882 </intro>
883
884 <intro id="mUTF" label="Modified UTF-8 String Encoding">
885 <jvmti/> uses modified UTF-8 to encode character strings.
886 This is the same encoding used by JNI.
887 Modified UTF-8 differs
888 from standard UTF-8 in the representation of supplementary characters
889 and of the null character. See the
890 <externallink id="jni/types.html#modified-utf-8-strings">
891 Modified UTF-8 Strings</externallink>
892 section of the JNI specification for details.
893 </intro>
894
895 <intro id="context" label="Specification Context">
896 Since this interface provides access to the state of applications running in the
897 Java virtual machine;
898 terminology refers to the Java platform and not the native
899 platform (unless stated otherwise). For example:
900 <ul>
901 <li>"thread" means Java programming language thread.</li>
902 <li>"stack frame" means Java virtual machine stack frame.</li>
903 <li>"class" means Java programming language class.</li>
904 <li>"heap" means Java virtual machine heap.</li>
905 <li>"monitor" means Java programming language object monitor.</li>
906 </ul>
907 <p/>
908 Sun, Sun Microsystems, the Sun logo, Java, and JVM
909 are trademarks or registered trademarks of Oracle
910 and/or its affiliates, in the U.S. and other countries.
911 </intro>
912
913
914 <functionsection label="Functions">
915 <intro id="jvmtiEnvAccess" label="Accessing Functions">
916 Native code accesses <jvmti/> features
917 by calling <jvmti/> functions.
918 Access to <jvmti/> functions is by use of an interface pointer
919 in the same manner as
920 <externallink id="jni/design.html">Java
921 Native Interface (JNI) functions</externallink> are accessed.
922 The <jvmti/> interface pointer is called the
923 <i>environment pointer</i>.
924 <p/>
925 An environment pointer is a pointer to an environment and has
926 the type <code>jvmtiEnv*</code>.
927 An environment has information about its <jvmti/> connection.
928 The first value in the environment is a pointer to the function table.
929 The function table is an array of pointers to <jvmti/> functions.
930 Every function pointer is at a predefined offset inside the
931 array.
932 <p/>
933 When used from the C language:
934 double indirection is used to access the functions;
935 the environment pointer provides context and is the first
936 parameter of each function call; for example:
937 <example>
938 jvmtiEnv *jvmti;
939 ...
940 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes);
941 </example>
942 <p/>
943 When used from the C++ language:
944 functions are accessed as member functions of <code>jvmtiEnv</code>;
945 the environment pointer is not passed to the function call; for example:
946 <example>
947 jvmtiEnv *jvmti;
948 ...
949 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes);
950 </example>
951 Unless otherwise stated, all examples and declarations in this
952 specification use the C language.
953 <p/>
954 A <jvmti/> environment can be obtained through the JNI Invocation API
955 <code>GetEnv</code> function:
956 <example>
957 jvmtiEnv *jvmti;
958 ...
959 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0);
960 </example>
961 Each call to <code>GetEnv</code>
962 creates a new <jvmti/> connection and thus
963 a new <jvmti/> environment.
964 The <code>version</code> argument of <code>GetEnv</code> must be
965 a <jvmti/> version.
966 The returned environment may have a different version than the
967 requested version but the returned environment must be compatible.
968 <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a
969 compatible version is not available, if <jvmti/> is not supported or
970 <jvmti/> is not supported in the current VM configuration.
971 Other interfaces may be added for creating <jvmti/> environments
972 in specific contexts.
973 Each environment has its own state (for example,
974 <functionlink id="SetEventNotificationMode">desired events</functionlink>,
975 <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and
976 <functionlink id="AddCapabilities">capabilities</functionlink>).
977 An environment is released with
978 <functionlink id="DisposeEnvironment"></functionlink>.
979 Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
980 across threads and are created dynamically.
981 </intro>
982
983 <intro id="functionReturn" label="Function Return Values">
984 <jvmti/> functions always return an
985 <internallink id="ErrorSection">error code</internallink> via the
986 <datalink id="jvmtiError"/> function return value.
987 Some functions can return additional
988 values through pointers provided by the calling function.
989 In some cases, <jvmti/> functions allocate memory that your program must
990 explicitly deallocate. This is indicated in the individual <jvmti/>
991 function descriptions. Empty lists, arrays, sequences, etc are
992 returned as <code>NULL</code>.
993 <p/>
994 In the event that the <jvmti/> function encounters
995 an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
996 of memory referenced by argument pointers is undefined, but no memory
997 will have been allocated and no global references will have been allocated.
998 If the error occurs because of invalid input, no action will have occurred.
999 </intro>
1000
1001 <intro id="refs" label="Managing JNI Object References">
1002 <jvmti/> functions identify objects with JNI references
1003 (<datalink id="jobject"/> and <datalink id="jclass"/>)
1004 and their derivatives
1005 (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1006 References passed to
1007 <jvmti/> functions can be either global or local, but they must be
1008 strong references. All references returned by <jvmti/> functions are
1009 local references--these local references are created
1010 during the <jvmti/> call.
1011 Local references are a resource that must be managed (see the
1012 <externallink id="jni/functions.html#local-references">
1013 JNI Documentation</externallink>).
1014 When threads return from native code all local references
1015 are freed. Note that some threads, including typical
1016 agent threads, will never return from native code.
1017 A thread is ensured the ability to create sixteen local
1018 references without the need for any explicit management.
1019 For threads executing a limited number of <jvmti/> calls before
1020 returning from native code
1021 (for example, threads processing events),
1022 it may be determined that no explicit management
1023 is needed.
1024 However, long running agent threads will need explicit
1025 local reference management--usually with the JNI functions
1026 <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1027 Conversely, to preserve references beyond the
1028 return from native code, they must be converted to global references.
1029 These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>
1030 as they are not <datalink id="jobject"/>s.
1031 </intro>
1032
1033 <intro id="prereqState" label="Prerequisite State for Calling Functions">
1034 Unless the function explicitly states that the agent must bring
1035 a thread or the VM to a particular state (for example, suspended),
1036 the <jvmti/> implementation is responsible for bringing the VM to a
1037 safe and consistent state for performing the function.
1038 </intro>
1039
1040 <intro id="functionsExceptions" label="Exceptions and Functions">
1041 <jvmti/> functions never throw exceptions; error conditions are
1042 communicated via the
1043 <internallink id="functionReturn">function return value</internallink>.
1044 Any existing exception state is preserved across a call to a
1045 <jvmti/> function.
1046 See the
1047 <externallink
1048 id="jni/design.html#java-exceptions"
1049 >Java Exceptions</externallink>
1050 section of the JNI specification for information on handling exceptions.
1051 </intro>
1052
1053 <category id="memory" label="Memory Management">
1054 <intro>
1055 These functions provide for the allocation and deallocation of
1056 memory used by <jvmti/> functionality and can be used to provide
1057 working memory for agents.
1058 Memory managed by <jvmti/> is not compatible with other memory
1059 allocation libraries and mechanisms.
1060 </intro>
1061
1062 <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1063 <synopsis>Allocate</synopsis>
1064 <description>
1065 Allocate an area of memory through the <jvmti/> allocator.
1066 The allocated
1067 memory should be freed with <functionlink id="Deallocate"></functionlink>.
1068 </description>
1069 <origin>jvmdi</origin>
1070 <capabilities>
1071 </capabilities>
1072 <parameters>
1073 <param id="size">
1074 <jlong/>
1075 <description>
1076 The number of bytes to allocate.
1077 <rationale>
1078 <code>jlong</code> is used for compatibility with JVMDI.
1079 </rationale>
1080 </description>
1081 </param>
1082 <param id="mem_ptr">
1083 <allocbuf incount="size"><uchar/></allocbuf>
1084 <description>
1085 On return, a pointer to the beginning of the allocated memory.
1086 If <code>size</code> is zero, <code>NULL</code> is returned.
1087 </description>
1088 </param>
1089 </parameters>
1090 <errors>
1091 <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1092 Memory request cannot be honored.
1093 </error>
1094 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1095 <paramlink id="size"></paramlink> is less than zero.
1096 </error>
1097 </errors>
1098 </function>
1099
1100 <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1101 <synopsis>Deallocate</synopsis>
1102 <description>
1103 Deallocate <code>mem</code> using the <jvmti/> allocator.
1104 This function should
1105 be used to deallocate any memory allocated and returned
1106 by a <jvmti/> function
1107 (including memory allocated with <functionlink id="Allocate"></functionlink>).
1108 All allocated memory must be deallocated
1109 or the memory cannot be reclaimed.
1110 </description>
1111 <origin>jvmdi</origin>
1112 <capabilities>
1113 </capabilities>
1114 <parameters>
1115 <param id="mem">
1116 <outbuf>
1117 <uchar/>
1118 <nullok>the call is ignored</nullok>
1119 </outbuf>
1120 <description>
1121 A pointer to the beginning of the allocated memory.
1122 Please ignore "On return, the elements are set."
1123 <todo>keep it from generating "On return, the elements are set"</todo>
1124 </description>
1125 </param>
1126 </parameters>
1127 <errors>
1128 </errors>
1129 </function>
1130 </category>
1131
1132 <category id="threadCategory" label="Thread">
1133 <intro>
1134 These functions provide information about threads and allow an agent to
1135 suspend and resume threads.
1136 <p/>
1137 The <code>jthread</code> specified to these functions can be a JNI
1138 reference to a
1139 <externallink id="../api/java.base/java/lang/Thread.html#platform-threads">platform thread</externallink>
1140 or <externallink id="../api/java.base/java/lang/Thread.html#virtual-threads">virtual thread</externallink>.
1141 Some functions are not supported on virtual threads and return
1142 <code>JVMTI_ERROR_UNSUPPORTED_OPERATION</code> when called with a reference
1143 to a virtual thread.
1144 </intro>
1145
1146 <function id="GetThreadState" num="17">
1147 <synopsis>Get Thread State</synopsis>
1148 <description>
1149 Get the state of a thread. The state of the thread is represented by the
1150 answers to the hierarchical set of questions below:
1151 <ul type="circle">
1152 <li><i>Alive?</i>
1153 <ul>
1154 <li>Not alive.
1155 <ul type="circle">
1156 <li><i>Why not alive?</i>
1157 <ul>
1158 <li>New.</li>
1159 <li>Terminated (<datalink
1160 id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1161 </ul>
1162 </li>
1163 </ul>
1164 </li>
1165 <li>Alive (<datalink
1166 id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1167 <ul type="circle">
1168 <li><i>Suspended?</i>
1169 <ul>
1170 <li>Suspended (<datalink
1171 id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1172 <li>Not suspended</li>
1173 </ul>
1174 </li>
1175 <li><i>Interrupted?</i>
1176 <ul>
1177 <li>Interrupted (<datalink
1178 id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1179 <li>Not interrupted.</li>
1180 </ul>
1181 </li>
1182 <li><i>In native?</i>
1183 <ul>
1184 <li>In native code (<datalink
1185 id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1186 <li>In Java programming language code</li>
1187 </ul>
1188 </li>
1189 <li><i>What alive state?</i>
1190 <ul>
1191 <li>Runnable (<datalink
1192 id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1193 <li>Blocked (<datalink
1194 id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1195 <li>Waiting (<datalink
1196 id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1197 <ul type="circle">
1198 <li><i>Timed wait?</i>
1199 <ul>
1200 <li>Indefinite (<datalink
1201 id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1202 <li>Timed (<datalink
1203 id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1204 </ul>
1205 </li>
1206 <li><i>Why waiting?</i>
1207 <ul>
1208 <li>Object.wait (<datalink
1209 id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1210 <li>LockSupport.park (<datalink
1211 id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1212 <li>Sleeping (<datalink
1213 id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1214 </ul>
1215 </li>
1216 </ul>
1217 </li>
1218 </ul>
1219 </li>
1220 </ul>
1221 </li>
1222 </ul>
1223 </li>
1224 </ul>
1225 <p/>
1226 The answers are represented by the following bit vector.
1227 <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1228 <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1229 Thread is alive. Zero if thread is new (not started) or terminated.
1230 </constant>
1231 <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1232 Thread has completed execution.
1233 </constant>
1234 <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1235 Thread is runnable.
1236 </constant>
1237 <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1238 Thread is waiting to enter a synchronized block/method or,
1239 after an <code>Object.wait()</code>, waiting to re-enter a
1240 synchronized block/method.
1241 </constant>
1242 <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1243 Thread is waiting.
1244 </constant>
1245 <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1246 Thread is waiting without a timeout.
1247 For example, <code>Object.wait()</code>.
1248 </constant>
1249 <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1250 Thread is waiting with a maximum time to wait specified.
1251 For example, <code>Object.wait(long)</code>.
1252 </constant>
1253 <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1254 Thread is sleeping -- <code>Thread.sleep</code>.
1255 </constant>
1256 <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1257 Thread is waiting on an object monitor -- <code>Object.wait</code>.
1258 </constant>
1259 <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1260 Thread is parked, for example: <code>LockSupport.park</code>,
1261 <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1262 A virtual thread that is sleeping, in <code>Thread.sleep</code>, may
1263 have this state flag set instead of <code>JVMTI_THREAD_STATE_SLEEPING</code>.
1264 </constant>
1265 <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1266 Thread is suspended by a suspend function
1267 (such as <functionlink id="SuspendThread"></functionlink>).
1268 If this bit is set, the other bits refer to the thread state before
1269 suspension.
1270 </constant>
1271 <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1272 Thread has been interrupted.
1273 </constant>
1274 <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1275 Thread is in native code--that is, a native method is running
1276 which has not called back into the VM or Java programming
1277 language code.
1278 <p/>
1279 This flag is not set when running VM compiled Java programming
1280 language code nor is it set when running VM code or
1281 VM support code. Native VM interface functions, such as JNI and
1282 <jvmti/> functions, may be implemented as VM code.
1283 </constant>
1284 <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1285 Defined by VM vendor.
1286 </constant>
1287 <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1288 Defined by VM vendor.
1289 </constant>
1290 <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1291 Defined by VM vendor.
1292 </constant>
1293 </constants>
1294 The following definitions are used to convert <jvmti/> thread state
1295 to <code>java.lang.Thread.State</code> style states.
1296 <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1297 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1298 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">
1299 Mask the state with this before comparison
1300 </constant>
1301 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1302 num="0">
1303 <code>java.lang.Thread.State.NEW</code>
1304 </constant>
1305 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1306 num="JVMTI_THREAD_STATE_TERMINATED">
1307 <code>java.lang.Thread.State.TERMINATED</code>
1308 </constant>
1309 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1310 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1311 <code>java.lang.Thread.State.RUNNABLE</code>
1312 </constant>
1313 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1314 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1315 <code>java.lang.Thread.State.BLOCKED</code>
1316 </constant>
1317 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1318 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1319 <code>java.lang.Thread.State.WAITING</code>
1320 </constant>
1321 <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1322 num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1323 <code>java.lang.Thread.State.TIMED_WAITING</code>
1324 </constant>
1325 </constants>
1326 <b>Rules</b>
1327 <p/>
1328 There can be no more than one answer to a question, although there can be no
1329 answer (because the answer is unknown, does not apply, or none of the answers is
1330 correct). An answer is set only when the enclosing answers match.
1331 That is, no more than one of
1332 <ul type="circle">
1333 <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1334 <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1335 <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1336 </ul>
1337 can be set (a <tm>J2SE</tm> compliant implementation will always set
1338 one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).
1339 And if any of these are set, the enclosing answer
1340 <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1341 No more than one of
1342 <ul type="circle">
1343 <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1344 <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1345 </ul>
1346 can be set (a <tm>J2SE</tm> compliant implementation will always set
1347 one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).
1348 And if either is set, the enclosing answers
1349 <code>JVMTI_THREAD_STATE_ALIVE</code> and
1350 <code>JVMTI_THREAD_STATE_WAITING</code> are set.
1351 No more than one of
1352 <ul type="circle">
1353 <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1354 <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1355 <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1356 </ul>
1357 can be set. And if any of these is set, the enclosing answers
1358 <code>JVMTI_THREAD_STATE_ALIVE</code> and
1359 <code>JVMTI_THREAD_STATE_WAITING</code> are set.
1360 Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1361 then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1362 If a state <i>A</i> is implemented using the mechanism of
1363 state <i>B</i> then it is state <i>A</i> which
1364 is returned by this function.
1365 For example, if <code>Thread.sleep(long)</code>
1366 is implemented using <code>Object.wait(long)</code>
1367 then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1368 which is returned.
1369 More than one of
1370 <ul type="circle">
1371 <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1372 <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1373 <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1374 </ul>
1375 can be set, but if any is set,
1376 <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1377 <p/>
1378 And finally,
1379 <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1380 <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.
1381 <p/>
1382 The thread state representation is designed for extension in future versions
1383 of the specification; thread state values should be used accordingly, that is
1384 they should not be used as ordinals.
1385 Most queries can be made by testing a single bit, if use in a switch statement is desired,
1386 the state bits should be masked with the interesting bits.
1387 All bits not defined above are reserved for future use.
1388 A VM, compliant to the current specification, must set reserved bits to zero.
1389 An agent should ignore reserved bits --
1390 they should not be assumed to be zero and thus should not be included in comparisons.
1391 <p/>
1392 <b>Examples</b>
1393 <p/>
1394 Note that the values below exclude reserved and vendor bits.
1395 <p/>
1396 The state of a thread blocked at a <code>synchronized</code>-statement would be:
1397 <example>
1398 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1399 </example>
1400 The state of a thread which hasn't started yet would be:
1401 <example>
1402 0
1403 </example>
1404 The state of a thread at a <code>Object.wait(3000)</code> would be:
1405 <example>
1406 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
1407 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
1408 JVMTI_THREAD_STATE_MONITOR_WAITING
1409 </example>
1410 The state of a thread suspended while runnable would be:
1411 <example>
1412 JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1413 </example>
1414 <p/>
1415 <b>Testing the State</b>
1416 <p/>
1417 In most cases, the thread state can be determined by testing the one bit corresponding
1418 to that question. For example, the code to test if a thread is sleeping:
1419 <example>
1420 jint state;
1421 jvmtiError err;
1422
1423 err = (*jvmti)->GetThreadState(jvmti, thread, &state);
1424 if (err == JVMTI_ERROR_NONE) {
1425 if (state & JVMTI_THREAD_STATE_SLEEPING) { ...
1426 </example>
1427 <p/>
1428 For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1429 <example>
1430 if (state & JVMTI_THREAD_STATE_WAITING) { ...
1431 </example>
1432 For some states, more than one bit will need to be tested as is the case
1433 when testing if a thread has not yet been started:
1434 <example>
1435 if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0) { ...
1436 </example>
1437 To distinguish timed from untimed <code>Object.wait</code>:
1438 <example>
1439 if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT) {
1440 if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT) {
1441 printf("in Object.wait(long timeout)\n");
1442 } else {
1443 printf("in Object.wait()\n");
1444 }
1445 }
1446 </example>
1447 <p/>
1448 <b>Relationship to <code>java.lang.Thread.State</code></b>
1449 <p/>
1450 The thread state represented by <code>java.lang.Thread.State</code>
1451 returned from <code>java.lang.Thread.getState()</code> is a subset of the
1452 information returned from this function.
1453 The corresponding <code>java.lang.Thread.State</code> can be determined
1454 by using the provided conversion masks.
1455 For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1456 <example>
1457 err = (*jvmti)->GetThreadState(jvmti, thread, &state);
1458 abortOnError(err);
1459 switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1460 case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1461 return "NEW";
1462 case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1463 return "TERMINATED";
1464 case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1465 return "RUNNABLE";
1466 case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1467 return "BLOCKED";
1468 case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1469 return "WAITING";
1470 case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1471 return "TIMED_WAITING";
1472 }
1473 </example>
1474 </description>
1475 <origin>new</origin>
1476 <capabilities>
1477 </capabilities>
1478 <parameters>
1479 <param id="thread">
1480 <jthread null="current" started="maybe" impl="noconvert"/>
1481 <description>
1482 The thread to query.
1483 </description>
1484 </param>
1485 <param id="thread_state_ptr">
1486 <outptr><jint/></outptr>
1487 <description>
1488 On return, points to state flags,
1489 as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1490 </description>
1491 </param>
1492 </parameters>
1493 <errors>
1494 </errors>
1495 </function>
1496
1497 <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1498 <synopsis>Get Current Thread</synopsis>
1499 <description>
1500 Get the current thread.
1501 The current thread is the Java programming language thread which has called the function.
1502 The function may return <code>NULL</code> in the start phase if the
1503 <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
1504 <code>can_generate_early_vmstart</code></internallink> capability is enabled
1505 and the <code>java.lang.Thread</code> class has not been initialized yet.
1506 <p/>
1507 Note that most <jvmti/> functions that take a thread
1508 as an argument will accept <code>NULL</code> to mean
1509 the current thread.
1510 </description>
1511 <origin>new</origin>
1512 <capabilities>
1513 </capabilities>
1514 <parameters>
1515 <param id="thread_ptr">
1516 <outptr><jthread/></outptr>
1517 <description>
1518 On return, points to the current thread, or <code>NULL</code>.
1519 </description>
1520 </param>
1521 </parameters>
1522 <errors>
1523 </errors>
1524 </function>
1525
1526 <function id="GetAllThreads" num="4">
1527 <synopsis>Get All Threads</synopsis>
1528 <description>
1529 Get all live platform threads that are attached to the VM.
1530 The list of threads includes
1531 <internallink id="RunAgentThread">agent threads</internallink>.
1532 It does not include virtual threads.
1533 A thread is live if <code>java.lang.Thread.isAlive()</code>
1534 would return <code>true</code>, that is, the thread has
1535 been started and has not yet terminated.
1536 The universe of threads is determined by the context of the <jvmti/>
1537 environment, which typically is all threads attached to the VM.
1538 </description>
1539 <origin>jvmdi</origin>
1540 <capabilities>
1541 </capabilities>
1542 <parameters>
1543 <param id="threads_count_ptr">
1544 <outptr><jint/></outptr>
1545 <description>
1546 On return, points to the number of threads.
1547 </description>
1548 </param>
1549 <param id="threads_ptr">
1550 <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1551 <description>
1552 On return, points to an array of references, one
1553 for each thread.
1554 </description>
1555 </param>
1556 </parameters>
1557 <errors>
1558 </errors>
1559 </function>
1560
1561 <function id="SuspendThread" num="5">
1562 <synopsis>Suspend Thread</synopsis>
1563 <description>
1564 Suspend the specified thread. If the calling thread is specified,
1565 this function will not return until some other thread calls
1566 <functionlink id="ResumeThread"></functionlink>.
1567 If the thread is currently suspended, this function
1568 does nothing and returns an error.
1569 </description>
1570 <origin>jvmdi</origin>
1571 <capabilities>
1572 <required id="can_suspend"></required>
1573 </capabilities>
1574 <parameters>
1575 <param id="thread">
1576 <jthread null="current" impl="noconvert"/>
1577 <description>
1578 The thread to suspend.
1579 </description>
1580 </param>
1581 </parameters>
1582 <errors>
1583 <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1584 Thread already suspended.
1585 </error>
1586 </errors>
1587 </function>
1588
1589 <elide>
1590 <function id="SuspendAllThreads" num="101">
1591 <synopsis>Suspend All Threads</synopsis>
1592 <description>
1593 <issue>
1594 There has been no explicit call for this function, and it will
1595 thus be removed if there is no interest.
1596 </issue>
1597 Suspend all live threads except:
1598 <ul>
1599 <li>already suspended threads</li>
1600 <li>those listed in <paramlink id="except_list"></paramlink></li>
1601 <li>certain system (non application) threads, as determined
1602 by the VM implementation</li>
1603 </ul>
1604 The threads are Java programming language threads;
1605 native threads which are not attached to the VM are not
1606 Java programming language threads.
1607 A thread is live if <code>java.lang.Thread.isAlive()</code>
1608 would return <code>true</code>, that is, the thread has
1609 been started and has not yet terminated.
1610 The universe of threads is determined
1611 by the context of the <jvmti/>
1612 environment, which, typically, is all threads attached to the VM,
1613 except critical VM internal threads and <jvmti/> agent threads
1614 (see <functionlink id="RunAgentThread"/>).
1615 <p/>
1616 If the calling thread is specified,
1617 all other threads are suspended first then the caller thread is suspended -
1618 this function will not return until some other thread calls
1619 <functionlink id="ResumeThread"></functionlink>.
1620 <p/>
1621 The list of actually
1622 suspended threads is returned in
1623 <paramlink id="suspended_list_ptr"></paramlink>.
1624 Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1625 <functionlink id="ResumeThreadList"></functionlink>
1626 can be used to resume the suspended threads.
1627 </description>
1628 <origin>new</origin>
1629 <capabilities>
1630 <required id="can_suspend"></required>
1631 </capabilities>
1632 <parameters>
1633 <param id="except_count">
1634 <jint min="0"/>
1635 <description>
1636 The number of threads in the list of threads not to be suspended.
1637 </description>
1638 </param>
1639 <param id="except_list">
1640 <inbuf incount="except_count">
1641 <jthread/>
1642 <nullok>not an error if <code>except_count == 0</code></nullok>
1643 </inbuf>
1644 <description>
1645 The list of threads not to be suspended.
1646 </description>
1647 </param>
1648 <param id="suspended_count_ptr">
1649 <outptr><jint/></outptr>
1650 <description>
1651 On return, points to the number of threads suspended by this call.
1652 </description>
1653 </param>
1654 <param id="suspended_list_ptr">
1655 <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1656 <description>
1657 On return, points to an array of references, one
1658 for each thread suspended.
1659 </description>
1660 </param>
1661 </parameters>
1662 <errors>
1663 <error id="JVMTI_ERROR_INVALID_THREAD">
1664 A thread in <paramlink id="except_list"></paramlink> was invalid.
1665 </error>
1666 <error id="JVMTI_ERROR_NULL_POINTER">
1667 Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1668 and <paramlink id="except_count"></paramlink> was non-zero.
1669 </error>
1670 </errors>
1671 </function>
1672 </elide>
1673
1674 <function id="SuspendThreadList" num="92">
1675 <synopsis>Suspend Thread List</synopsis>
1676 <description>
1677 Suspend the <paramlink id="request_count"></paramlink>
1678 threads specified in the
1679 <paramlink id="request_list"></paramlink> array.
1680 Threads may be resumed with
1681 <functionlink id="ResumeThreadList"></functionlink> or
1682 <functionlink id="ResumeThread"></functionlink>.
1683 If the calling thread is specified in the
1684 <paramlink id="request_list"></paramlink> array, this function will
1685 not return until some other thread resumes it.
1686 Errors encountered in the suspension of a thread
1687 are returned in the <paramlink id="results"></paramlink>
1688 array, <b>not</b> in the return value of this function.
1689 Threads that are currently suspended do not change state.
1690 </description>
1691 <origin>jvmdi</origin>
1692 <capabilities>
1693 <required id="can_suspend"></required>
1694 </capabilities>
1695 <parameters>
1696 <param id="request_count">
1697 <jint min="0"/>
1698 <description>
1699 The number of threads to suspend.
1700 </description>
1701 </param>
1702 <param id="request_list">
1703 <inbuf incount="request_count"><jthread/></inbuf>
1704 <description>
1705 The list of threads to suspend.
1706 </description>
1707 </param>
1708 <param id="results">
1709 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1710 <description>
1711 An agent supplied array of
1712 <paramlink id="request_count"></paramlink> elements.
1713 On return, filled with the error code for
1714 the suspend of the corresponding thread.
1715 The error code will be
1716 <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1717 if the thread was suspended by this call.
1718 Possible error codes are those specified
1719 for <functionlink id="SuspendThread"></functionlink>.
1720 </description>
1721 </param>
1722 </parameters>
1723 <errors>
1724 </errors>
1725 </function>
1726
1727 <function id="SuspendAllVirtualThreads" num="118" since="21">
1728 <synopsis>Suspend All Virtual Threads</synopsis>
1729 <description>
1730 Suspend all virtual threads except those in the exception list.
1731 Virtual threads that are currently suspended do not change state.
1732 Virtual threads may be resumed with
1733 <functionlink id="ResumeAllVirtualThreads"></functionlink> or
1734 <functionlink id="ResumeThreadList"></functionlink> or
1735 <functionlink id="ResumeThread"></functionlink>.
1736 </description>
1737 <origin>new</origin>
1738 <capabilities>
1739 <required id="can_suspend"></required>
1740 <required id="can_support_virtual_threads">Can support virtual threads</required>
1741 </capabilities>
1742 <parameters>
1743 <param id="except_count">
1744 <jint min="0"/>
1745 <description>
1746 The number of threads in the list of threads not to be suspended.
1747 </description>
1748 </param>
1749 <param id="except_list">
1750 <inbuf incount="except_count">
1751 <jthread/>
1752 <nullok>not an error if <code>except_count == 0</code></nullok>
1753 </inbuf>
1754 <description>
1755 The list of threads not to be suspended.
1756 </description>
1757 </param>
1758 </parameters>
1759 <errors>
1760 <error id="JVMTI_ERROR_INVALID_THREAD">
1761 A thread in <paramlink id="except_list"></paramlink> was invalid.
1762 </error>
1763 <error id="JVMTI_ERROR_NULL_POINTER">
1764 Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1765 and <paramlink id="except_count"></paramlink> was non-zero.
1766 </error>
1767 </errors>
1768 </function>
1769
1770 <function id="ResumeThread" num="6">
1771 <synopsis>Resume Thread</synopsis>
1772 <description>
1773 Resume a suspended thread.
1774 Any threads currently suspended through
1775 a <jvmti/> suspend function (eg.
1776 <functionlink id="SuspendThread"></functionlink>)
1777 will resume execution;
1778 all other threads are unaffected.
1779 </description>
1780 <origin>jvmdi</origin>
1781 <capabilities>
1782 <required id="can_suspend"></required>
1783 </capabilities>
1784 <parameters>
1785 <param id="thread">
1786 <jthread impl="noconvert"/>
1787 <description>
1788 The thread to resume.
1789 </description>
1790 </param>
1791 </parameters>
1792 <errors>
1793 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1794 Thread was not suspended.
1795 </error>
1796 <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1797 The state of the thread has been modified, and is now inconsistent.
1798 </error>
1799 </errors>
1800 </function>
1801
1802 <function id="ResumeThreadList" num="93">
1803 <synopsis>Resume Thread List</synopsis>
1804 <description>
1805 Resume the <paramlink id="request_count"></paramlink>
1806 threads specified in the
1807 <paramlink id="request_list"></paramlink> array.
1808 Any thread suspended through
1809 a <jvmti/> suspend function (eg.
1810 <functionlink id="SuspendThreadList"></functionlink>)
1811 will resume execution.
1812 </description>
1813 <origin>jvmdi</origin>
1814 <capabilities>
1815 <required id="can_suspend"></required>
1816 </capabilities>
1817 <parameters>
1818 <param id="request_count">
1819 <jint min="0"/>
1820 <description>
1821 The number of threads to resume.
1822 </description>
1823 </param>
1824 <param id="request_list">
1825 <inbuf incount="request_count"><jthread/></inbuf>
1826 <description>
1827 The threads to resume.
1828 </description>
1829 </param>
1830 <param id="results">
1831 <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1832 <description>
1833 An agent supplied array of
1834 <paramlink id="request_count"></paramlink> elements.
1835 On return, filled with the error code for
1836 the resume of the corresponding thread.
1837 The error code will be
1838 <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1839 if the thread was suspended by this call.
1840 Possible error codes are those specified
1841 for <functionlink id="ResumeThread"></functionlink>.
1842 </description>
1843 </param>
1844 </parameters>
1845 <errors>
1846 </errors>
1847 </function>
1848
1849 <function id="ResumeAllVirtualThreads" num="119" since="21">
1850 <synopsis>Resume All Virtual Threads</synopsis>
1851 <description>
1852 Resume all virtual threads except those in the exception list.
1853 Virtual threads that are currently resumed do not change state.
1854 Virtual threads may be suspended with
1855 <functionlink id="SuspendAllVirtualThreads"></functionlink> or
1856 <functionlink id="SuspendThreadList"></functionlink> or
1857 <functionlink id="SuspendThread"></functionlink>.
1858 </description>
1859 <origin>new</origin>
1860 <capabilities>
1861 <required id="can_suspend"></required>
1862 <required id="can_support_virtual_threads">Can support virtual threads</required>
1863 </capabilities>
1864 <parameters>
1865 <param id="except_count">
1866 <jint min="0"/>
1867 <description>
1868 The number of threads in the list of threads not to be resumed.
1869 </description>
1870 </param>
1871 <param id="except_list">
1872 <inbuf incount="except_count">
1873 <jthread/>
1874 <nullok>not an error if <code>except_count == 0</code></nullok>
1875 </inbuf>
1876 <description>
1877 The list of threads not to be resumed.
1878 </description>
1879 </param>
1880 </parameters>
1881 <errors>
1882 <error id="JVMTI_ERROR_INVALID_THREAD">
1883 A thread in <paramlink id="except_list"></paramlink> was invalid.
1884 </error>
1885 <error id="JVMTI_ERROR_NULL_POINTER">
1886 Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1887 and <paramlink id="except_count"></paramlink> was non-zero.
1888 </error>
1889 </errors>
1890 </function>
1891
1892 <function id="StopThread" num="7">
1893 <synopsis>Stop Thread</synopsis>
1894 <description>
1895 Send the specified asynchronous exception to the specified platform thread.
1896 </description>
1897 <origin>jvmdi</origin>
1898 <capabilities>
1899 <required id="can_signal_thread"></required>
1900 </capabilities>
1901 <parameters>
1902 <param id="thread">
1903 <jthread impl="noconvert"/>
1904 <description>
1905 The thread to stop.
1906 The <code>thread</code> may not be a virtual thread. Otherwise, the error code
1907 <errorlink id="JVMTI_ERROR_UNSUPPORTED_OPERATION"></errorlink> will be returned.
1908 </description>
1909 </param>
1910 <param id="exception">
1911 <jobject/>
1912 <description>
1913 The asynchronous exception object.
1914 </description>
1915 </param>
1916 </parameters>
1917 <errors>
1918 <error id="JVMTI_ERROR_UNSUPPORTED_OPERATION">
1919 <paramlink id="thread"/> is a virtual thread.
1920 </error>
1921 </errors>
1922 </function>
1923
1924 <function id="InterruptThread" num="8">
1925 <synopsis>Interrupt Thread</synopsis>
1926 <description>
1927 Interrupt the specified thread
1928 (similar to <code>java.lang.Thread.interrupt</code>).
1929 </description>
1930 <origin>jvmdi</origin>
1931 <capabilities>
1932 <required id="can_signal_thread"></required>
1933 </capabilities>
1934 <parameters>
1935 <param id="thread">
1936 <jthread impl="noconvert"/>
1937 <description>
1938 The thread to interrupt.
1939 </description>
1940 </param>
1941 </parameters>
1942 <errors>
1943 </errors>
1944 </function>
1945
1946 <function id="GetThreadInfo" num="9">
1947 <synopsis>Get Thread Info</synopsis>
1948 <typedef id="jvmtiThreadInfo" label="Thread information structure">
1949 <field id="name">
1950 <allocfieldbuf><char/></allocfieldbuf>
1951 <description>
1952 The thread name, encoded as a
1953 <internallink id="mUTF">modified UTF-8</internallink> string.
1954 </description>
1955 </field>
1956 <field id="priority">
1957 <jint/>
1958 <description>
1959 The thread priority. See the thread priority constants:
1960 <datalink id="jvmtiThreadPriority"></datalink>. The priority of a
1961 virtual thread is always <code>JVMTI_THREAD_NORM_PRIORITY</code>.
1962 </description>
1963 </field>
1964 <field id="is_daemon">
1965 <jboolean/>
1966 <description>
1967 Is this a daemon thread? The daemon status of a virtual thread is
1968 always <code>JNI_TRUE</code>.
1969 </description>
1970 </field>
1971 <field id="thread_group">
1972 <jthreadGroup/>
1973 <description>
1974 The thread group to which this thread belongs.
1975 <code>NULL</code> if the thread has terminated.
1976 </description>
1977 </field>
1978 <field id="context_class_loader">
1979 <jobject/>
1980 <description>
1981 The context class loader associated with this thread.
1982 </description>
1983 </field>
1984 </typedef>
1985 <description>
1986 Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
1987 are filled in with details of the specified thread.
1988 </description>
1989 <origin>jvmdi</origin>
1990 <capabilities>
1991 </capabilities>
1992 <parameters>
1993 <param id="thread">
1994 <jthread null="current" impl="noconvert" started="maybe"/>
1995 <description>
1996 The thread to query.
1997 </description>
1998 </param>
1999 <param id="info_ptr">
2000 <outptr><struct>jvmtiThreadInfo</struct></outptr>
2001 <description>
2002 On return, filled with information describing the specified thread.
2003 </description>
2004 </param>
2005 </parameters>
2006 <errors>
2007 </errors>
2008 </function>
2009
2010 <function id="GetOwnedMonitorInfo" num="10">
2011 <synopsis>Get Owned Monitor Info</synopsis>
2012 <description>
2013 Get information about the monitors owned by the
2014 specified thread.
2015 </description>
2016 <origin>jvmdiClone</origin>
2017 <capabilities>
2018 <required id="can_get_owned_monitor_info"></required>
2019 </capabilities>
2020 <parameters>
2021 <param id="thread">
2022 <jthread null="current" impl="noconvert"/>
2023 <description>
2024 The thread to query.
2025 </description>
2026 </param>
2027 <param id="owned_monitor_count_ptr">
2028 <outptr><jint/></outptr>
2029 <description>
2030 The number of monitors returned.
2031 </description>
2032 </param>
2033 <param id="owned_monitors_ptr">
2034 <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
2035 <description>
2036 The array of owned monitors.
2037 </description>
2038 </param>
2039 </parameters>
2040 <errors>
2041 </errors>
2042 </function>
2043
2044 <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
2045 <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
2046 <typedef id="jvmtiMonitorStackDepthInfo"
2047 label="Monitor stack depth information structure">
2048 <field id="monitor">
2049 <jobject/>
2050 <description>
2051 The owned monitor.
2052 </description>
2053 </field>
2054 <field id="stack_depth">
2055 <jint/>
2056 <description>
2057 The stack depth. Corresponds to the stack depth used in the
2058 <internallink id="stack">Stack Frame functions</internallink>.
2059 That is, zero is the current frame, one is the frame which
2060 called the current frame. And it is negative one if the
2061 implementation cannot determine the stack depth (e.g., for
2062 monitors acquired by JNI <code>MonitorEnter</code>).
2063 </description>
2064 </field>
2065 </typedef>
2066 <description>
2067 Get information about the monitors owned by the
2068 specified thread and the depth of the stack frame which locked them.
2069 </description>
2070 <origin>new</origin>
2071 <capabilities>
2072 <required id="can_get_owned_monitor_stack_depth_info"></required>
2073 </capabilities>
2074 <parameters>
2075 <param id="thread">
2076 <jthread null="current" impl="noconvert"/>
2077 <description>
2078 The thread to query.
2079 </description>
2080 </param>
2081 <param id="monitor_info_count_ptr">
2082 <outptr><jint/></outptr>
2083 <description>
2084 The number of monitors returned.
2085 </description>
2086 </param>
2087 <param id="monitor_info_ptr">
2088 <allocbuf outcount="monitor_info_count_ptr">
2089 <struct>jvmtiMonitorStackDepthInfo</struct>
2090 </allocbuf>
2091 <description>
2092 The array of owned monitor depth information.
2093 </description>
2094 </param>
2095 </parameters>
2096 <errors>
2097 </errors>
2098 </function>
2099
2100 <function id="GetCurrentContendedMonitor" num="11">
2101 <synopsis>Get Current Contended Monitor</synopsis>
2102 <description>
2103 Get the object, if any, whose monitor the specified thread is waiting to
2104 enter or waiting to regain through <code>java.lang.Object.wait</code>.
2105 </description>
2106 <origin>jvmdi</origin>
2107 <capabilities>
2108 <required id="can_get_current_contended_monitor"></required>
2109 </capabilities>
2110 <parameters>
2111 <param id="thread">
2112 <jthread null="current" impl="noconvert"/>
2113 <description>
2114 The thread to query.
2115 </description>
2116 </param>
2117 <param id="monitor_ptr">
2118 <outptr><jobject/></outptr>
2119 <description>
2120 On return, filled with the current contended monitor, or
2121 NULL if there is none.
2122 </description>
2123 </param>
2124 </parameters>
2125 <errors>
2126 </errors>
2127 </function>
2128
2129 <callback id="jvmtiStartFunction">
2130 <void/>
2131 <synopsis>Agent Start Function</synopsis>
2132 <description>
2133 Agent supplied callback function.
2134 This function is the entry point for an agent thread
2135 started with
2136 <functionlink id="RunAgentThread"></functionlink>.
2137 </description>
2138 <parameters>
2139 <param id="jvmti_env">
2140 <outptr>
2141 <struct>jvmtiEnv</struct>
2142 </outptr>
2143 <description>
2144 The <jvmti/> environment.
2145 </description>
2146 </param>
2147 <param id="jni_env">
2148 <outptr>
2149 <struct>JNIEnv</struct>
2150 </outptr>
2151 <description>
2152 The JNI environment.
2153 </description>
2154 </param>
2155 <param id="arg">
2156 <outptr>
2157 <void/>
2158 </outptr>
2159 <description>
2160 The <code>arg</code> parameter passed to
2161 <functionlink id="RunAgentThread"></functionlink>.
2162 </description>
2163 </param>
2164 </parameters>
2165 </callback>
2166
2167 <function id="RunAgentThread" num="12">
2168 <synopsis>Run Agent Thread</synopsis>
2169 <description>
2170 Starts the execution of an agent thread. with the specified native function.
2171 The parameter <paramlink id="arg"></paramlink> is forwarded on to the
2172 <functionlink id="jvmtiStartFunction">start function</functionlink>
2173 (specified with <paramlink id="proc"></paramlink>) as its single argument.
2174 This function allows the creation of agent threads
2175 for handling communication with another process or for handling events
2176 without the need to load a special subclass of <code>java.lang.Thread</code> or
2177 implementer of <code>java.lang.Runnable</code>.
2178 Instead, the created thread can run entirely in native code.
2179 However, the created thread does require a newly created instance
2180 of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to
2181 which it will be associated.
2182 The thread object can be created with JNI calls.
2183 <p/>
2184 The following common thread priorities are provided for your convenience:
2185 <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
2186 <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
2187 Minimum possible thread priority
2188 </constant>
2189 <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2190 Normal thread priority
2191 </constant>
2192 <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2193 Maximum possible thread priority
2194 </constant>
2195 </constants>
2196 <p/>
2197 The new thread is started as a daemon thread with the specified
2198 <paramlink id="priority"></paramlink>.
2199 If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2200 <p/>
2201 Since the thread has been started, the thread will be live when this function
2202 returns, unless the thread terminated immediately.
2203 <p/>
2204 The thread group of the thread is ignored -- specifically, the thread is not
2205 added to the thread group and the thread is not seen on queries of the thread
2206 group at either the Java programming language or <jvmti/> levels.
2207 <p/>
2208 The thread is not visible to Java programming language queries but is
2209 included in <jvmti/> queries (for example,
2210 <functionlink id="GetAllThreads"/> and
2211 <functionlink id="GetAllStackTraces"/>).
2212 <p/>
2213 Upon execution of <code>proc</code>, the new thread will be attached to the
2214 VM -- see the JNI documentation on
2215 <externallink id="jni/invocation.html#attaching-to-the-vm"
2216 >Attaching to the VM</externallink>.
2217 </description>
2218 <origin>jvmdiClone</origin>
2219 <capabilities>
2220 </capabilities>
2221 <parameters>
2222 <param id="thread">
2223 <jthread impl="noconvert" started="no"/>
2224 <description>
2225 The thread to run.
2226 The <code>thread</code> may not be a virtual thread. Otherwise, the error code
2227 <errorlink id="JVMTI_ERROR_UNSUPPORTED_OPERATION"></errorlink> will be returned.
2228 </description>
2229 </param>
2230 <param id="proc">
2231 <ptrtype>
2232 <struct>jvmtiStartFunction</struct>
2233 </ptrtype>
2234 <description>
2235 The start function.
2236 </description>
2237 </param>
2238 <param id="arg">
2239 <inbuf>
2240 <void/>
2241 <nullok><code>NULL</code> is passed to the start function</nullok>
2242 </inbuf>
2243 <description>
2244 The argument to the start function.
2245 </description>
2246 </param>
2247 <param id="priority">
2248 <jint/>
2249 <description>
2250 The priority of the started thread. Any thread
2251 priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2252 those in <datalink id="jvmtiThreadPriority"></datalink>.
2253 </description>
2254 </param>
2255 </parameters>
2256 <errors>
2257 <error id="JVMTI_ERROR_INVALID_PRIORITY">
2258 <paramlink id="priority"/> is less than
2259 <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2260 or greater than
2261 <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2262 </error>
2263 <error id="JVMTI_ERROR_UNSUPPORTED_OPERATION">
2264 <paramlink id="thread"/> is a virtual thread.
2265 </error>
2266 </errors>
2267 </function>
2268
2269 <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2270 <synopsis>Set Thread Local Storage</synopsis>
2271 <description>
2272 The VM stores a pointer value associated with each environment-thread
2273 pair. This pointer value is called <i>thread-local storage</i>.
2274 This value is <code>NULL</code> unless set with this function.
2275 Agents can allocate memory in which they store thread specific
2276 information. By setting thread-local storage it can then be
2277 accessed with
2278 <functionlink id="GetThreadLocalStorage"></functionlink>.
2279 <p/>
2280 This function is called by the agent to set the value of the <jvmti/>
2281 thread-local storage. <jvmti/> supplies to the agent a pointer-size
2282 thread-local storage that can be used to record per-thread
2283 information.
2284 </description>
2285 <origin>jvmpi</origin>
2286 <capabilities>
2287 </capabilities>
2288 <parameters>
2289 <param id="thread">
2290 <jthread null="current" impl="noconvert"/>
2291 <description>
2292 Store to this thread.
2293 </description>
2294 </param>
2295 <param id="data">
2296 <inbuf>
2297 <void/>
2298 <nullok>value is set to <code>NULL</code></nullok>
2299 </inbuf>
2300 <description>
2301 The value to be entered into the thread-local storage.
2302 </description>
2303 </param>
2304 </parameters>
2305 <errors>
2306 </errors>
2307 </function>
2308
2309 <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2310 <synopsis>Get Thread Local Storage</synopsis>
2311 <description>
2312 Called by the agent to get the value of the <jvmti/> thread-local
2313 storage.
2314 </description>
2315 <origin>jvmpi</origin>
2316 <capabilities>
2317 </capabilities>
2318 <parameters>
2319 <param id="thread">
2320 <jthread null="current" impl="noconvert"/>
2321 <description>
2322 Retrieve from this thread.
2323 </description>
2324 </param>
2325 <param id="data_ptr">
2326 <agentbuf><void/></agentbuf>
2327 <description>
2328 Pointer through which the value of the thread local
2329 storage is returned.
2330 If thread-local storage has not been set with
2331 <functionlink id="SetThreadLocalStorage"></functionlink> the returned
2332 pointer is <code>NULL</code>.
2333 </description>
2334 </param>
2335 </parameters>
2336 <errors>
2337 </errors>
2338 </function>
2339
2340 </category>
2341
2342 <category id="thread_groups" label="Thread Group">
2343 <intro>
2344 </intro>
2345
2346 <function id="GetTopThreadGroups" num="13">
2347 <synopsis>Get Top Thread Groups</synopsis>
2348 <description>
2349 Return all top-level (parentless) thread groups in the VM.
2350 </description>
2351 <origin>jvmdi</origin>
2352 <capabilities>
2353 </capabilities>
2354 <parameters>
2355 <param id="group_count_ptr">
2356 <outptr><jint/></outptr>
2357 <description>
2358 On return, points to the number of top-level thread groups.
2359 </description>
2360 </param>
2361 <param id="groups_ptr">
2362 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2363 <description>
2364 On return, refers to a pointer to the top-level thread group array.
2365 </description>
2366 </param>
2367 </parameters>
2368 <errors>
2369 </errors>
2370 </function>
2371
2372 <function id="GetThreadGroupInfo" num="14">
2373 <synopsis>Get Thread Group Info</synopsis>
2374 <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2375 <field id="parent">
2376 <jthreadGroup/>
2377 <description>
2378 The parent thread group.
2379 </description>
2380 </field>
2381 <field id="name">
2382 <allocfieldbuf><char/></allocfieldbuf>
2383 <description>
2384 The thread group's name, encoded as a
2385 <internallink id="mUTF">modified UTF-8</internallink> string.
2386 </description>
2387 </field>
2388 <field id="max_priority">
2389 <jint/>
2390 <description>
2391 The maximum priority for this thread group.
2392 </description>
2393 </field>
2394 <field id="is_daemon">
2395 <jboolean/>
2396 <description>
2397 Is this a daemon thread group?
2398 </description>
2399 </field>
2400 </typedef>
2401 <description>
2402 Get information about the thread group. The fields of the
2403 <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
2404 are filled in with details of the specified thread group.
2405 </description>
2406 <origin>jvmdi</origin>
2407 <capabilities>
2408 </capabilities>
2409 <parameters>
2410 <param id="group">
2411 <jthreadGroup/>
2412 <description>
2413 The thread group to query.
2414 </description>
2415 </param>
2416 <param id="info_ptr">
2417 <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2418 <description>
2419 On return, filled with information describing the specified
2420 thread group.
2421 </description>
2422 </param>
2423 </parameters>
2424 <errors>
2425 </errors>
2426 </function>
2427
2428 <function id="GetThreadGroupChildren" num="15">
2429 <synopsis>Get Thread Group Children</synopsis>
2430 <description>
2431 Get the live platform threads and the child thread groups in this
2432 thread group. Virtual threads are not returned by this function.
2433 </description>
2434 <origin>jvmdi</origin>
2435 <capabilities>
2436 </capabilities>
2437 <parameters>
2438 <param id="group">
2439 <jthreadGroup/>
2440 <description>
2441 The group to query.
2442 </description>
2443 </param>
2444 <param id="thread_count_ptr">
2445 <outptr><jint/></outptr>
2446 <description>
2447 On return, points to the number of live threads in this thread group.
2448 </description>
2449 </param>
2450 <param id="threads_ptr">
2451 <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2452 <description>
2453 On return, points to an array of the live threads in this thread group.
2454 </description>
2455 </param>
2456 <param id="group_count_ptr">
2457 <outptr><jint/></outptr>
2458 <description>
2459 On return, points to the number of child thread groups
2460 </description>
2461 </param>
2462 <param id="groups_ptr">
2463 <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2464 <description>
2465 On return, points to an array of the child thread groups.
2466 </description>
2467 </param>
2468 </parameters>
2469 <errors>
2470 </errors>
2471 </function>
2472 </category>
2473
2474 <category id="stack" label="Stack Frame">
2475 <intro>
2476 These functions provide information about the stack of a thread.
2477 Stack frames are referenced by depth.
2478 The frame at depth zero is the current frame.
2479 <p/>
2480 Stack frames are as described in
2481 <vmspec chapter="3.6"/>,
2482 That is, they correspond to method
2483 invocations (including native methods) but do not correspond to platform native or
2484 VM internal frames.
2485 <p/>
2486 A <jvmti/> implementation may use method invocations to launch a thread and
2487 the corresponding frames may be included in the stack as presented by these functions --
2488 that is, there may be frames shown
2489 deeper than <code>main()</code> and <code>run()</code>.
2490 However this presentation must be consistent across all <jvmti/> functionality which
2491 uses stack frames or stack depth.
2492 </intro>
2493
2494 <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2495 <description>
2496 Information about a stack frame is returned in this structure.
2497 </description>
2498 <field id="method">
2499 <jmethodID/>
2500 <description>
2501 The method executing in this frame.
2502 </description>
2503 </field>
2504 <field id="location">
2505 <jlocation/>
2506 <description>
2507 The index of the instruction executing in this frame.
2508 <code>-1</code> if the frame is executing a native method.
2509 </description>
2510 </field>
2511 </typedef>
2512
2513 <typedef id="jvmtiStackInfo" label="Stack information structure">
2514 <description>
2515 Information about a set of stack frames is returned in this structure.
2516 </description>
2517 <field id="thread">
2518 <jthread/>
2519 <description>
2520 On return, the thread traced.
2521 </description>
2522 </field>
2523 <field id="state">
2524 <jint/>
2525 <description>
2526 On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2527 </description>
2528 </field>
2529 <field id="frame_buffer">
2530 <outbuf incount="max_frame_count">
2531 <struct>jvmtiFrameInfo</struct>
2532 </outbuf>
2533 <description>
2534 On return, this agent allocated buffer is filled
2535 with stack frame information.
2536 </description>
2537 </field>
2538 <field id="frame_count">
2539 <jint/>
2540 <description>
2541 On return, the number of records filled into
2542 <code>frame_buffer</code>.
2543 This will be
2544 min(<code>max_frame_count</code>, <i>stackDepth</i>).
2545 </description>
2546 </field>
2547 </typedef>
2548
2549 <function id="GetStackTrace" num="104">
2550 <synopsis>Get Stack Trace</synopsis>
2551 <description>
2552 Get information about the stack of a thread.
2553 If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2554 the <paramlink id="max_frame_count"></paramlink> topmost frames are returned,
2555 otherwise the entire stack is returned.
2556 The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2557 <p/>
2558 The following example causes up to five of the topmost frames
2559 to be returned and (if there are any frames) the currently
2560 executing method name to be printed.
2561 <example>
2562 jvmtiFrameInfo frames[5];
2563 jint count;
2564 jvmtiError err;
2565
2566 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5,
2567 frames, &count);
2568 if (err == JVMTI_ERROR_NONE && count >= 1) {
2569 char *methodName;
2570 err = (*jvmti)->GetMethodName(jvmti, frames[0].method,
2571 &methodName, NULL, NULL);
2572 if (err == JVMTI_ERROR_NONE) {
2573 printf("Executing method: %s", methodName);
2574 }
2575 }
2576 </example>
2577 <todo>
2578 check example code.
2579 </todo>
2580 <p/>
2581 The <paramlink id="thread"></paramlink> need not be suspended
2582 to call this function.
2583 <p/>
2584 The <functionlink id="GetLineNumberTable"></functionlink>
2585 function can be used to map locations to line numbers. Note that
2586 this mapping can be done lazily.
2587 </description>
2588 <origin>jvmpi</origin>
2589 <capabilities>
2590 </capabilities>
2591 <parameters>
2592 <param id="thread">
2593 <jthread null="current" impl="noconvert"/>
2594 <description>
2595 Fetch the stack trace of this thread.
2596 </description>
2597 </param>
2598 <param id="start_depth">
2599 <jint/>
2600 <description>
2601 Begin retrieving frames at this depth.
2602 If non-negative, count from the current frame,
2603 the first frame retrieved is at depth <code>start_depth</code>.
2604 For example, if zero, start from the current frame; if one, start from the
2605 caller of the current frame; if two, start from the caller of the
2606 caller of the current frame; and so on.
2607 If negative, count from below the oldest frame,
2608 the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
2609 where <i>stackDepth</i> is the count of frames on the stack.
2610 For example, if negative one, only the oldest frame is retrieved;
2611 if negative two, start from the frame called by the oldest frame.
2612 </description>
2613 </param>
2614 <param id="max_frame_count">
2615 <jint min="0"/>
2616 <description>
2617 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2618 </description>
2619 </param>
2620 <param id="frame_buffer">
2621 <outbuf incount="max_frame_count" outcount="count_ptr">
2622 <struct>jvmtiFrameInfo</struct>
2623 </outbuf>
2624 <description>
2625 On return, this agent allocated buffer is filled
2626 with stack frame information.
2627 </description>
2628 </param>
2629 <param id="count_ptr">
2630 <outptr><jint/></outptr>
2631 <description>
2632 On return, points to the number of records filled in.
2633 For non-negative <code>start_depth</code>, this will be
2634 min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2635 For negative <code>start_depth</code>, this will be
2636 min(<code>max_frame_count</code>, <code>-start_depth</code>).
2637 </description>
2638 </param>
2639 </parameters>
2640 <errors>
2641 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2642 <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2643 Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2644 </error>
2645 </errors>
2646 </function>
2647
2648
2649 <function id="GetAllStackTraces" num="100">
2650 <synopsis>Get All Stack Traces</synopsis>
2651 <description>
2652 Get the stack traces of all live platform threads attached to the VM.
2653 The list includes the stack traces of
2654 <internallink id="RunAgentThread">agent threads</internallink>.
2655 It does not include the stack traces of virtual threads.
2656 <p/>
2657 If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2658 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
2659 otherwise the entire stack is returned.
2660 The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2661 <p/>
2662 All stacks are collected simultaneously, that is, no changes will occur to the
2663 thread state or stacks between the sampling of one thread and the next.
2664 The threads need not be suspended.
2665
2666 <example>
2667 jvmtiStackInfo *stack_info;
2668 jint thread_count;
2669 int ti;
2670 jvmtiError err;
2671
2672 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count);
2673 if (err != JVMTI_ERROR_NONE) {
2674 ...
2675 }
2676 for (ti = 0; ti < thread_count; ++ti) {
2677 jvmtiStackInfo *infop = &stack_info[ti];
2678 jthread thread = infop->thread;
2679 jint state = infop->state;
2680 jvmtiFrameInfo *frames = infop->frame_buffer;
2681 int fi;
2682
2683 myThreadAndStatePrinter(thread, state);
2684 for (fi = 0; fi < infop->frame_count; fi++) {
2685 myFramePrinter(frames[fi].method, frames[fi].location);
2686 }
2687 }
2688 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2689 err = (*jvmti)->Deallocate(jvmti, stack_info);
2690 </example>
2691 <todo>
2692 check example code.
2693 </todo>
2694
2695 </description>
2696 <origin>new</origin>
2697 <capabilities>
2698 </capabilities>
2699 <parameters>
2700 <param id="max_frame_count">
2701 <jint min="0"/>
2702 <description>
2703 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2704 </description>
2705 </param>
2706 <param id="stack_info_ptr">
2707 <allocbuf>
2708 <struct>jvmtiStackInfo</struct>
2709 </allocbuf>
2710 <description>
2711 On return, this buffer is filled
2712 with stack information for each thread.
2713 The number of <datalink id="jvmtiStackInfo"/> records is determined
2714 by <paramlink id="thread_count_ptr"/>.
2715 <p/>
2716 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
2717 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2718 These buffers must not be separately deallocated.
2719 </description>
2720 </param>
2721 <param id="thread_count_ptr">
2722 <outptr><jint/></outptr>
2723 <description>
2724 The number of threads traced.
2725 </description>
2726 </param>
2727 </parameters>
2728 <errors>
2729 </errors>
2730 </function>
2731
2732 <function id="GetThreadListStackTraces" num="101">
2733 <synopsis>Get Thread List Stack Traces</synopsis>
2734 <description>
2735 Get information about the stacks of the supplied threads.
2736 If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2737 the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
2738 otherwise the entire stack is returned.
2739 The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2740 <p/>
2741 All stacks are collected simultaneously, that is, no changes will occur to the
2742 thread state or stacks between the sampling one thread and the next.
2743 The threads need not be suspended.
2744 <p/>
2745 If a thread has not yet started or terminates before the stack information is collected,
2746 a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2747 will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2748 <p/>
2749 See the example for the similar function
2750 <functionlink id="GetAllStackTraces"/>.
2751 </description>
2752 <origin>new</origin>
2753 <capabilities>
2754 </capabilities>
2755 <parameters>
2756 <param id="thread_count">
2757 <jint min="0"/>
2758 <description>
2759 The number of threads to trace.
2760 </description>
2761 </param>
2762 <param id="thread_list">
2763 <inbuf incount="thread_count"><jthread/></inbuf>
2764 <description>
2765 The list of threads to trace.
2766 </description>
2767 </param>
2768 <param id="max_frame_count">
2769 <jint min="0"/>
2770 <description>
2771 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2772 </description>
2773 </param>
2774 <param id="stack_info_ptr">
2775 <allocbuf outcount="thread_count">
2776 <struct>jvmtiStackInfo</struct>
2777 </allocbuf>
2778 <description>
2779 On return, this buffer is filled
2780 with stack information for each thread.
2781 The number of <datalink id="jvmtiStackInfo"/> records is determined
2782 by <paramlink id="thread_count"/>.
2783 <p/>
2784 Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
2785 buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2786 These buffers must not be separately deallocated.
2787 </description>
2788 </param>
2789 </parameters>
2790 <errors>
2791 <error id="JVMTI_ERROR_INVALID_THREAD">
2792 An element in <paramlink id="thread_list"/> is not a thread object.
2793 </error>
2794 </errors>
2795 </function>
2796
2797 <elide>
2798 <function id="AsyncGetStackTrace" num="1000">
2799 <synopsis>Get Stack Trace--Asynchronous</synopsis>
2800 <description>
2801 Get information about the entire stack of a thread (or a sub-section of it).
2802 This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2803 and is reentrant and safe to call
2804 from asynchronous signal handlers.
2805 The stack trace is returned only for the calling thread.
2806 <p/>
2807 The <functionlink id="GetLineNumberTable"></functionlink>
2808 function can be used to map locations to line numbers. Note that
2809 this mapping can be done lazily.
2810 </description>
2811 <origin>jvmpi</origin>
2812 <capabilities>
2813 <required id="can_get_async_stack_trace"></required>
2814 <capability id="can_show_JVM_spec_async_frames">
2815 If <code>false</code>,
2816 <paramlink id="use_java_stack"></paramlink>
2817 must be <code>false</code>.
2818 </capability>
2819 </capabilities>
2820 <parameters>
2821 <param id="use_java_stack">
2822 <jboolean/>
2823 <description>
2824 Return the stack showing <vmspec/>
2825 model of the stack;
2826 otherwise, show the internal representation of the stack with
2827 inlined and optimized methods missing. If the virtual machine
2828 is using the <i>Java Virtual Machine Specification</i> stack model
2829 internally, this flag is ignored.
2830 </description>
2831 </param>
2832 <param id="max_count">
2833 <jint min="0"/>
2834 <description>
2835 The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2836 Retrieve this many unless the stack depth is less than <code>max_count</code>.
2837 </description>
2838 </param>
2839 <param id="frame_buffer">
2840 <outbuf incount="max_count" outcount="count_ptr">
2841 <struct>jvmtiFrameInfo</struct>
2842 <nullok>this information is not returned</nullok>
2843 </outbuf>
2844 <description>
2845 The agent passes in a buffer
2846 large enough to hold <code>max_count</code> records of
2847 <datalink id="jvmtiFrameInfo"></datalink>. This buffer must be
2848 pre-allocated by the agent.
2849 </description>
2850 </param>
2851 <param id="count_ptr">
2852 <outptr><jint/></outptr>
2853 <description>
2854 On return, points to the number of records filled in..
2855 </description>
2856 </param>
2857 </parameters>
2858 <errors>
2859 <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2860 The thread being used to call this function is not attached
2861 to the virtual machine. Calls must be made from attached threads.
2862 </error>
2863 </errors>
2864 </function>
2865 </elide>
2866
2867 <function id="GetFrameCount" num="16">
2868 <synopsis>Get Frame Count</synopsis>
2869 <description>
2870 Get the number of frames currently in the specified thread's call stack.
2871 <p/>
2872 If this function is called for a thread actively executing bytecodes (for example,
2873 not the current thread and not suspended), the information returned is transient.
2874 </description>
2875 <origin>jvmdi</origin>
2876 <capabilities>
2877 </capabilities>
2878 <parameters>
2879 <param id="thread">
2880 <jthread null="current" impl="noconvert"/>
2881 <description>
2882 The thread to query.
2883 </description>
2884 </param>
2885 <param id="count_ptr">
2886 <outptr><jint/></outptr>
2887 <description>
2888 On return, points to the number of frames in the call stack.
2889 </description>
2890 </param>
2891 </parameters>
2892 <errors>
2893 </errors>
2894 </function>
2895
2896 <function id="PopFrame" num="80">
2897 <synopsis>Pop Frame</synopsis>
2898 <description>
2899 Pop the current frame of <code>thread</code>'s stack.
2900 Popping a frame takes you to the previous frame.
2901 When the thread is resumed, the execution
2902 state of the thread is reset to the state
2903 immediately before the called method was invoked.
2904 That is (using <vmspec/> terminology):
2905 <ul>
2906 <li>the current frame is discarded as the previous frame becomes the current one</li>
2907 <li>the operand stack is restored--the argument values are added back
2908 and if the invoke was not <code>invokestatic</code>,
2909 <code>objectref</code> is added back as well</li>
2910 <li>the Java virtual machine PC is restored to the opcode
2911 of the invoke instruction</li>
2912 </ul>
2913 Note however, that any changes to the arguments, which
2914 occurred in the called method, remain;
2915 when execution continues, the first instruction to
2916 execute will be the invoke.
2917 <p/>
2918 Between calling <code>PopFrame</code> and resuming the
2919 thread the state of the stack is undefined.
2920 To pop frames beyond the first,
2921 these three steps must be repeated:
2922 <ul>
2923 <li>suspend the thread via an event (step, breakpoint, ...)</li>
2924 <li>call <code>PopFrame</code></li>
2925 <li>resume the thread</li>
2926 </ul>
2927 <p/>
2928 A lock acquired by calling the called method
2929 (if it is a <code>synchronized</code> method)
2930 and locks acquired by entering <code>synchronized</code>
2931 blocks within the called method are released.
2932 Note: this does not apply to native locks or
2933 <code>java.util.concurrent.locks</code> locks.
2934 <p/>
2935 Finally blocks are not executed.
2936 <p/>
2937 Changes to global state are not addressed and thus remain changed.
2938 <p/>
2939 The specified thread must be suspended or must be the current thread.
2940 <p/>
2941 Both the called method and calling method must be non-native Java programming
2942 language methods.
2943 <p/>
2944 No <jvmti/> events are generated by this function.
2945 </description>
2946 <origin>jvmdi</origin>
2947 <capabilities>
2948 <required id="can_pop_frame"></required>
2949 </capabilities>
2950 <parameters>
2951 <param id="thread">
2952 <jthread impl="noconvert"/>
2953 <description>
2954 The thread whose current frame is to be popped.
2955 </description>
2956 </param>
2957 </parameters>
2958 <errors>
2959 <error id="JVMTI_ERROR_OPAQUE_FRAME">
2960 Called or calling method is a native method.
2961 The implementation is unable to pop this frame.
2962 </error>
2963 <error id="JVMTI_ERROR_OPAQUE_FRAME">
2964 The thread is a virtual thread and the implementation is unable
2965 to pop this frame.
2966 </error>
2967 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2968 Thread was not suspended and was not the current thread.
2969 </error>
2970 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2971 There are less than two stack frames on the call stack.
2972 </error>
2973 </errors>
2974 </function>
2975
2976 <function id="GetFrameLocation" num="19">
2977 <synopsis>Get Frame Location</synopsis>
2978 <description>
2979 <p/>
2980 For a Java programming language frame, return the location of the instruction
2981 currently executing.
2982 </description>
2983 <origin>jvmdiClone</origin>
2984 <capabilities>
2985 </capabilities>
2986 <parameters>
2987 <param id="thread">
2988 <jthread null="current" frame="frame" impl="noconvert"/>
2989 <description>
2990 The thread of the frame to query.
2991 </description>
2992 </param>
2993 <param id="depth">
2994 <jframeID thread="thread"/>
2995 <description>
2996 The depth of the frame to query.
2997 </description>
2998 </param>
2999 <param id="method_ptr">
3000 <outptr><jmethodID/></outptr>
3001 <description>
3002 On return, points to the method for the current location.
3003 </description>
3004 </param>
3005 <param id="location_ptr">
3006 <outptr><jlocation/></outptr>
3007 <description>
3008 On return, points to the index of the currently
3009 executing instruction.
3010 Is set to <code>-1</code> if the frame is executing
3011 a native method.
3012 </description>
3013 </param>
3014 </parameters>
3015 <errors>
3016 </errors>
3017 </function>
3018
3019 <function id="NotifyFramePop" num="20">
3020 <synopsis>Notify Frame Pop</synopsis>
3021 <description>
3022 When the frame that is currently at <paramlink id="depth"></paramlink>
3023 is popped from the stack, generate a
3024 <eventlink id="FramePop"></eventlink> event. See the
3025 <eventlink id="FramePop"></eventlink> event for details.
3026 Only frames corresponding to non-native Java programming language
3027 methods can receive notification.
3028 <p/>
3029 The specified thread must be suspended or must be the current thread.
3030 </description>
3031 <origin>jvmdi</origin>
3032 <capabilities>
3033 <required id="can_generate_frame_pop_events"></required>
3034 </capabilities>
3035 <parameters>
3036 <param id="thread">
3037 <jthread null="current" frame="depth" impl="noconvert"/>
3038 <description>
3039 The thread of the frame for which the frame pop event will be generated.
3040 </description>
3041 </param>
3042 <param id="depth">
3043 <jframeID thread="thread"/>
3044 <description>
3045 The depth of the frame for which the frame pop event will be generated.
3046 </description>
3047 </param>
3048 </parameters>
3049 <errors>
3050 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3051 The frame at <code>depth</code> is executing a
3052 native method.
3053 </error>
3054 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3055 Thread was not suspended and was not the current thread.
3056 </error>
3057 </errors>
3058 </function>
3059
3060 </category>
3061
3062 <category id="ForceEarlyReturn" label="Force Early Return">
3063 <intro>
3064 These functions allow an agent to force a method
3065 to return at any point during its execution.
3066 The method which will return early is referred to as the <i>called method</i>.
3067 The called method is the current method
3068 (as defined by
3069 <vmspec chapter="3.6"/>)
3070 for the specified thread at
3071 the time the function is called.
3072 <p/>
3073 The specified thread must be suspended or must be the current thread.
3074 The return occurs when execution of Java programming
3075 language code is resumed on this thread.
3076 Between calling one of these functions and resumption
3077 of thread execution, the state of the stack is undefined.
3078 <p/>
3079 No further instructions are executed in the called method.
3080 Specifically, finally blocks are not executed.
3081 Note: this can cause inconsistent states in the application.
3082 <p/>
3083 A lock acquired by calling the called method
3084 (if it is a <code>synchronized</code> method)
3085 and locks acquired by entering <code>synchronized</code>
3086 blocks within the called method are released.
3087 Note: this does not apply to native locks or
3088 <code>java.util.concurrent.locks</code> locks.
3089 <p/>
3090 Events, such as <eventlink id="MethodExit"></eventlink>,
3091 are generated as they would be in a normal return.
3092 <p/>
3093 The called method must be a non-native Java programming
3094 language method.
3095 Forcing return on a thread with only one frame on the
3096 stack causes the thread to exit when resumed.
3097 </intro>
3098
3099 <function id="ForceEarlyReturnObject" num="81" since="1.1">
3100 <synopsis>Force Early Return - Object</synopsis>
3101 <description>
3102 This function can be used to return from a method whose
3103 result type is <code>Object</code>
3104 or a subclass of <code>Object</code>.
3105 </description>
3106 <origin>new</origin>
3107 <capabilities>
3108 <required id="can_force_early_return"></required>
3109 </capabilities>
3110 <parameters>
3111 <param id="thread">
3112 <jthread null="current" impl="noconvert"/>
3113 <description>
3114 The thread whose current frame is to return early.
3115 </description>
3116 </param>
3117 <param id="value">
3118 <jobject/>
3119 <description>
3120 The return value for the called frame.
3121 An object or <code>NULL</code>.
3122 </description>
3123 </param>
3124 </parameters>
3125 <errors>
3126 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3127 Attempted to return early from a frame
3128 corresponding to a native method.
3129 The thread is a virtual thread and the implementation is
3130 unable to force its current frame to return.
3131 Or the implementation is unable to provide
3132 this functionality on this frame.
3133 </error>
3134 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3135 The result type of the called method is not
3136 <code>Object</code> or a subclass of <code>Object</code>.
3137 </error>
3138 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3139 The supplied <paramlink id="value"/> is not compatible with the
3140 result type of the called method.
3141 </error>
3142 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3143 Thread was not suspended and was not the current thread.
3144 </error>
3145 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3146 There are no more frames on the call stack.
3147 </error>
3148 </errors>
3149 </function>
3150
3151 <function id="ForceEarlyReturnInt" num="82" since="1.1">
3152 <synopsis>Force Early Return - Int</synopsis>
3153 <description>
3154 This function can be used to return from a method whose
3155 result type is <code>int</code>, <code>short</code>,
3156 <code>char</code>, <code>byte</code>, or
3157 <code>boolean</code>.
3158 </description>
3159 <origin>new</origin>
3160 <capabilities>
3161 <required id="can_force_early_return"></required>
3162 </capabilities>
3163 <parameters>
3164 <param id="thread">
3165 <jthread null="current" impl="noconvert"/>
3166 <description>
3167 The thread whose current frame is to return early.
3168 </description>
3169 </param>
3170 <param id="value">
3171 <jint/>
3172 <description>
3173 The return value for the called frame.
3174 </description>
3175 </param>
3176 </parameters>
3177 <errors>
3178 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3179 Attempted to return early from a frame
3180 corresponding to a native method.
3181 The thread is a virtual thread and the implementation is
3182 unable to force its current frame to return.
3183 Or the implementation is unable to provide
3184 this functionality on this frame.
3185 </error>
3186 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3187 The result type of the called method is not
3188 <code>int</code>, <code>short</code>,
3189 <code>char</code>, <code>byte</code>, or
3190 <code>boolean</code>.
3191 </error>
3192 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3193 Thread was not suspended and was not the current thread.
3194 </error>
3195 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3196 There are no frames on the call stack.
3197 </error>
3198 </errors>
3199 </function>
3200
3201 <function id="ForceEarlyReturnLong" num="83" since="1.1">
3202 <synopsis>Force Early Return - Long</synopsis>
3203 <description>
3204 This function can be used to return from a method whose
3205 result type is <code>long</code>.
3206 </description>
3207 <origin>new</origin>
3208 <capabilities>
3209 <required id="can_force_early_return"></required>
3210 </capabilities>
3211 <parameters>
3212 <param id="thread">
3213 <jthread null="current" impl="noconvert"/>
3214 <description>
3215 The thread whose current frame is to return early.
3216 </description>
3217 </param>
3218 <param id="value">
3219 <jlong/>
3220 <description>
3221 The return value for the called frame.
3222 </description>
3223 </param>
3224 </parameters>
3225 <errors>
3226 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3227 Attempted to return early from a frame
3228 corresponding to a native method.
3229 The thread is a virtual thread and the implementation is
3230 unable to force its current frame to return.
3231 Or the implementation is unable to provide
3232 this functionality on this frame.
3233 </error>
3234 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3235 The result type of the called method is not <code>long</code>.
3236 </error>
3237 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3238 Thread was not suspended and was not the current thread.
3239 </error>
3240 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3241 There are no frames on the call stack.
3242 </error>
3243 </errors>
3244 </function>
3245
3246 <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3247 <synopsis>Force Early Return - Float</synopsis>
3248 <description>
3249 This function can be used to return from a method whose
3250 result type is <code>float</code>.
3251 </description>
3252 <origin>new</origin>
3253 <capabilities>
3254 <required id="can_force_early_return"></required>
3255 </capabilities>
3256 <parameters>
3257 <param id="thread">
3258 <jthread null="current" impl="noconvert"/>
3259 <description>
3260 The thread whose current frame is to return early.
3261 </description>
3262 </param>
3263 <param id="value">
3264 <jfloat/>
3265 <description>
3266 The return value for the called frame.
3267 </description>
3268 </param>
3269 </parameters>
3270 <errors>
3271 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3272 Attempted to return early from a frame
3273 corresponding to a native method.
3274 The thread is a virtual thread and the implementation is
3275 unable to force its current frame to return.
3276 Or the implementation is unable to provide
3277 this functionality on this frame.
3278 </error>
3279 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3280 The result type of the called method is not <code>float</code>.
3281 </error>
3282 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3283 Thread was not suspended and was not the current thread.
3284 </error>
3285 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3286 There are no frames on the call stack.
3287 </error>
3288 </errors>
3289 </function>
3290
3291 <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3292 <synopsis>Force Early Return - Double</synopsis>
3293 <description>
3294 This function can be used to return from a method whose
3295 result type is <code>double</code>.
3296 </description>
3297 <origin>new</origin>
3298 <capabilities>
3299 <required id="can_force_early_return"></required>
3300 </capabilities>
3301 <parameters>
3302 <param id="thread">
3303 <jthread null="current" impl="noconvert"/>
3304 <description>
3305 The thread whose current frame is to return early.
3306 </description>
3307 </param>
3308 <param id="value">
3309 <jdouble/>
3310 <description>
3311 The return value for the called frame.
3312 </description>
3313 </param>
3314 </parameters>
3315 <errors>
3316 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3317 Attempted to return early from a frame
3318 corresponding to a native method.
3319 The thread is a virtual thread and the implementation is
3320 unable to force its current frame to return.
3321 Or the implementation is unable to provide
3322 this functionality on this frame.
3323 </error>
3324 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3325 The result type of the called method is not <code>double</code>.
3326 </error>
3327 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3328 Thread was not suspended and was not the current thread.
3329 </error>
3330 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3331 There are no frames on the call stack.
3332 </error>
3333 </errors>
3334 </function>
3335
3336 <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3337 <synopsis>Force Early Return - Void</synopsis>
3338 <description>
3339 This function can be used to return from a method with no result type.
3340 That is, the called method must be declared <code>void</code>.
3341 </description>
3342 <origin>new</origin>
3343 <capabilities>
3344 <required id="can_force_early_return"></required>
3345 </capabilities>
3346 <parameters>
3347 <param id="thread">
3348 <jthread null="current" impl="noconvert"/>
3349 <description>
3350 The thread whose current frame is to return early.
3351 </description>
3352 </param>
3353 </parameters>
3354 <errors>
3355 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3356 Attempted to return early from a frame
3357 corresponding to a native method.
3358 The thread is a virtual thread and the implementation is
3359 unable to force its current frame to return.
3360 Or the implementation is unable to provide
3361 this functionality on this frame.
3362 </error>
3363 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3364 The called method has a result type.
3365 </error>
3366 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3367 Thread was not suspended and was not the current thread.
3368 </error>
3369 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3370 There are no frames on the call stack.
3371 </error>
3372 </errors>
3373 </function>
3374
3375 </category>
3376
3377 <category id="Heap" label="Heap">
3378 <intro>
3379 These functions are used to analyze the heap.
3380 Functionality includes the ability to view the objects in the
3381 heap and to tag these objects.
3382 </intro>
3383
3384 <intro id="objectTags" label="Object Tags">
3385 A <i>tag</i> is a value associated with an object.
3386 Tags are explicitly set by the agent using the
3387 <functionlink id="SetTag"></functionlink> function or by
3388 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
3389 <p/>
3390 Tags are local to the environment; that is, the tags of one
3391 environment are not visible in another.
3392 <p/>
3393 Tags are <code>jlong</code> values which can be used
3394 simply to mark an object or to store a pointer to more detailed
3395 information. Objects which have not been tagged have a
3396 tag of zero.
3397 Setting a tag to zero makes the object untagged.
3398 </intro>
3399
3400 <intro id="heapCallbacks" label="Heap Callback Functions">
3401 Heap functions which iterate through the heap and recursively
3402 follow object references use agent supplied callback functions
3403 to deliver the information.
3404 <p/>
3405 These heap callback functions must adhere to the following restrictions --
3406 These callbacks must not use JNI functions.
3407 These callbacks must not use <jvmti/> functions except
3408 <i>callback safe</i> functions which
3409 specifically allow such use (see the raw monitor, memory management,
3410 and environment local storage functions).
3411 <p/>
3412 An implementation may invoke a callback on an internal thread or
3413 the thread which called the iteration function.
3414 Heap callbacks are single threaded -- no more than one callback will
3415 be invoked at a time.
3416 <p/>
3417 The Heap Filter Flags can be used to prevent reporting
3418 based on the tag status of an object or its class.
3419 If no flags are set (the <code>jint</code> is zero), objects
3420 will not be filtered out.
3421
3422 <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3423 <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3424 Filter out tagged objects. Objects which are tagged are not included.
3425 </constant>
3426 <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3427 Filter out untagged objects. Objects which are not tagged are not included.
3428 </constant>
3429 <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3430 Filter out objects with tagged classes. Objects whose class is tagged are not included.
3431 </constant>
3432 <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3433 Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3434 </constant>
3435 </constants>
3436
3437 <p/>
3438 The Heap Visit Control Flags are returned by the heap callbacks
3439 and can be used to abort the iteration. For the
3440 <functionlink id="jvmtiHeapReferenceCallback">Heap
3441 Reference Callback</functionlink>, it can also be used
3442 to prune the graph of traversed references
3443 (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3444
3445 <constants id="jvmtiHeapVisitControl"
3446 label="Heap Visit Control Flags"
3447 kind="bits"
3448 since="1.1">
3449 <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3450 If we are visiting an object and if this callback
3451 was initiated by <functionlink id="FollowReferences"/>,
3452 traverse the references of this object.
3453 Otherwise ignored.
3454 </constant>
3455 <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3456 Abort the iteration. Ignore all other bits.
3457 </constant>
3458 </constants>
3459
3460 <p/>
3461 The Heap Reference Enumeration is provided by the
3462 <functionlink id="jvmtiHeapReferenceCallback">Heap
3463 Reference Callback</functionlink> and
3464 <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field
3465 Callback</functionlink> to
3466 describe the kind of reference
3467 being reported.
3468
3469 <constants id="jvmtiHeapReferenceKind"
3470 label="Heap Reference Enumeration"
3471 kind="enum"
3472 since="1.1">
3473 <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3474 Reference from an object to its class.
3475 </constant>
3476 <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3477 Reference from an object to the value of one of its instance fields.
3478 </constant>
3479 <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3480 Reference from an array to one of its elements.
3481 </constant>
3482 <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3483 Reference from a class to its class loader.
3484 </constant>
3485 <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3486 Reference from a class to its signers array.
3487 </constant>
3488 <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3489 Reference from a class to its protection domain.
3490 </constant>
3491 <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3492 Reference from a class to one of its interfaces.
3493 Note: interfaces are defined via a constant pool reference,
3494 so the referenced interfaces may also be reported with a
3495 <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3496 </constant>
3497 <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3498 Reference from a class to the value of one of its static fields.
3499 </constant>
3500 <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3501 Reference from a class to a resolved entry in the constant pool.
3502 </constant>
3503 <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3504 Reference from a class to its superclass.
3505 A callback is not sent if the superclass is <code>java.lang.Object</code>.
3506 Note: loaded classes define superclasses via a constant pool
3507 reference, so the referenced superclass may also be reported with
3508 a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3509 </constant>
3510 <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3511 Heap root reference: JNI global reference.
3512 </constant>
3513 <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3514 Heap root reference: System class.
3515 </constant>
3516 <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3517 Heap root reference: monitor.
3518 </constant>
3519 <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3520 Heap root reference: local variable on the stack.
3521 </constant>
3522 <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3523 Heap root reference: JNI local reference.
3524 </constant>
3525 <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3526 Heap root reference: Thread.
3527 </constant>
3528 <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3529 Heap root reference: other heap root reference.
3530 </constant>
3531 </constants>
3532
3533 <p/>
3534 Definitions for the single character type descriptors of
3535 primitive types.
3536
3537 <constants id="jvmtiPrimitiveType"
3538 label="Primitive Type Enumeration"
3539 kind="enum"
3540 since="1.1">
3541 <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3542 'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3543 </constant>
3544 <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3545 'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3546 </constant>
3547 <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3548 'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3549 </constant>
3550 <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3551 'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3552 </constant>
3553 <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3554 'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3555 </constant>
3556 <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3557 'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3558 </constant>
3559 <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3560 'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3561 </constant>
3562 <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3563 'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3564 </constant>
3565 </constants>
3566 </intro>
3567
3568 <typedef id="jvmtiHeapReferenceInfoField"
3569 label="Reference information structure for Field references"
3570 since="1.1">
3571 <description>
3572 Reference information returned for
3573 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and
3574 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3575 </description>
3576 <field id="index">
3577 <jint/>
3578 <description>
3579 For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the
3580 referrer object is not a class or an interface.
3581 In this case, <code>index</code> is the index of the field
3582 in the class of the referrer object.
3583 This class is referred to below as <i>C</i>.
3584 <p/>
3585 For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3586 the referrer object is a class (referred to below as <i>C</i>)
3587 or an interface (referred to below as <i>I</i>).
3588 In this case, <code>index</code> is the index of the field in
3589 that class or interface.
3590 <p/>
3591 If the referrer object is not an interface, then the field
3592 indices are determined as follows:
3593 <ul>
3594 <li>make a list of all the fields in <i>C</i> and its
3595 superclasses, starting with all the fields in
3596 <code>java.lang.Object</code> and ending with all the
3597 fields in <i>C</i>.</li>
3598 <li>Within this list, put
3599 the fields for a given class in the order returned by
3600 <functionlink id="GetClassFields"/>.</li>
3601 <li>Assign the fields in this list indices
3602 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
3603 is the count of the fields in all the interfaces
3604 implemented by <i>C</i>.
3605 Note that <i>C</i> implements all interfaces
3606 directly implemented by its superclasses; as well
3607 as all superinterfaces of these interfaces.</li>
3608 </ul>
3609 If the referrer object is an interface, then the field
3610 indices are determined as follows:
3611 <ul>
3612 <li>make a list of the fields directly declared in
3613 <i>I</i>.</li>
3614 <li>Within this list, put
3615 the fields in the order returned by
3616 <functionlink id="GetClassFields"/>.</li>
3617 <li>Assign the fields in this list indices
3618 <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
3619 is the count of the fields in all the superinterfaces
3620 of <i>I</i>.</li>
3621 </ul>
3622 All fields are included in this computation, regardless of
3623 field modifier (static, public, private, etc).
3624 <p/>
3625 For example, given the following classes and interfaces:
3626 <example>
3627 interface I0 {
3628 int p = 0;
3629 }
3630
3631 interface I1 extends I0 {
3632 int x = 1;
3633 }
3634
3635 interface I2 extends I0 {
3636 int y = 2;
3637 }
3638
3639 class C1 implements I1 {
3640 public static int a = 3;
3641 private int b = 4;
3642 }
3643
3644 class C2 extends C1 implements I2 {
3645 static int q = 5;
3646 final int r = 6;
3647 }
3648 </example>
3649 Assume that <functionlink id="GetClassFields"/> called on
3650 <code>C1</code> returns the fields of <code>C1</code> in the
3651 order: a, b; and that the fields of <code>C2</code> are
3652 returned in the order: q, r.
3653 An instance of class <code>C1</code> will have the
3654 following field indices:
3655 <blockquote><table>
3656 <tr class="bgLight">
3657 <th class="centered" scope="col">Field</th>
3658 <th class="centered" scope="col">Index</th>
3659 <th scope="col">Description</th>
3660 </tr>
3661 <tr>
3662 <th class="centered" scope="row">
3663 a
3664 </th>
3665 <td class="centered">
3666 2
3667 </td>
3668 <td>
3669 The count of the fields in the interfaces
3670 implemented by <code>C1</code> is two (<i>n</i>=2):
3671 <code>p</code> of <code>I0</code>
3672 and <code>x</code> of <code>I1</code>.
3673 </td>
3674 </tr>
3675 <tr>
3676 <th class="centered" scope="row">
3677 b
3678 </th>
3679 <td class="centered">
3680 3
3681 </td>
3682 <td>
3683 the subsequent index.
3684 </td>
3685 </tr>
3686 </table></blockquote>
3687 The class <code>C1</code> will have the same field indices.
3688 <p/>
3689 An instance of class <code>C2</code> will have the
3690 following field indices:
3691 <blockquote><table>
3692 <tr class="bgLight">
3693 <th class="centered" scope="col">Field</th>
3694 <th class="centered" scope="col">Index</th>
3695 <th scope="col">Description</th>
3696 </tr>
3697 <tr>
3698 <th class="centered" scope="row">
3699 a
3700 </th>
3701 <td class="centered">
3702 3
3703 </td>
3704 <td>
3705 The count of the fields in the interfaces
3706 implemented by <code>C2</code> is three (<i>n</i>=3):
3707 <code>p</code> of <code>I0</code>,
3708 <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code>
3709 (an interface of <code>C2</code>). Note that the field <code>p</code>
3710 of <code>I0</code> is only included once.
3711 </td>
3712 </tr>
3713 <tr>
3714 <th class="centered" scope="row">
3715 b
3716 </th>
3717 <td class="centered">
3718 4
3719 </td>
3720 <td>
3721 the subsequent index to "a".
3722 </td>
3723 </tr>
3724 <tr>
3725 <th class="centered" scope="row">
3726 q
3727 </th>
3728 <td class="centered">
3729 5
3730 </td>
3731 <td>
3732 the subsequent index to "b".
3733 </td>
3734 </tr>
3735 <tr>
3736 <th class="centered" scope="row">
3737 r
3738 </th>
3739 <td class="centered">
3740 6
3741 </td>
3742 <td>
3743 the subsequent index to "q".
3744 </td>
3745 </tr>
3746 </table></blockquote>
3747 The class <code>C2</code> will have the same field indices.
3748 Note that a field may have a different index depending on the
3749 object that is viewing it -- for example field "a" above.
3750 Note also: not all field indices may be visible from the
3751 callbacks, but all indices are shown for illustrative purposes.
3752 <p/>
3753 The interface <code>I1</code> will have the
3754 following field indices:
3755 <blockquote><table>
3756 <tr class="bgLight">
3757 <th class="centered" scope="col">Field</th>
3758 <th class="centered" scope="col">Index</th>
3759 <th scope="col">Description</th>
3760 </tr>
3761 <tr>
3762 <th class="centered" scope="row">
3763 x
3764 </th>
3765 <td class="centered">
3766 1
3767 </td>
3768 <td>
3769 The count of the fields in the superinterfaces
3770 of <code>I1</code> is one (<i>n</i>=1):
3771 <code>p</code> of <code>I0</code>.
3772 </td>
3773 </tr>
3774 </table></blockquote>
3775 </description>
3776 </field>
3777 </typedef>
3778
3779 <typedef id="jvmtiHeapReferenceInfoArray"
3780 label="Reference information structure for Array references"
3781 since="1.1">
3782 <description>
3783 Reference information returned for
3784 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3785 </description>
3786 <field id="index">
3787 <jint/>
3788 <description>
3789 The array index.
3790 </description>
3791 </field>
3792 </typedef>
3793
3794 <typedef id="jvmtiHeapReferenceInfoConstantPool"
3795 label="Reference information structure for Constant Pool references"
3796 since="1.1">
3797 <description>
3798 Reference information returned for
3799 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3800 </description>
3801 <field id="index">
3802 <jint/>
3803 <description>
3804 The index into the constant pool of the class. See the description in
3805 <vmspec chapter="4.4"/>.
3806 </description>
3807 </field>
3808 </typedef>
3809
3810 <typedef id="jvmtiHeapReferenceInfoStackLocal"
3811 label="Reference information structure for Local Variable references"
3812 since="1.1">
3813 <description>
3814 Reference information returned for
3815 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3816 </description>
3817 <field id="thread_tag">
3818 <jlong/>
3819 <description>
3820 The tag of the thread corresponding to this stack, zero if not tagged.
3821 </description>
3822 </field>
3823 <field id="thread_id">
3824 <jlong/>
3825 <description>
3826 The unique thread ID of the thread corresponding to this stack.
3827 </description>
3828 </field>
3829 <field id="depth">
3830 <jint/>
3831 <description>
3832 The depth of the frame.
3833 </description>
3834 </field>
3835 <field id="method">
3836 <jmethodID/>
3837 <description>
3838 The method executing in this frame.
3839 </description>
3840 </field>
3841 <field id="location">
3842 <jlocation/>
3843 <description>
3844 The currently executing location in this frame.
3845 </description>
3846 </field>
3847 <field id="slot">
3848 <jint/>
3849 <description>
3850 The slot number of the local variable.
3851 </description>
3852 </field>
3853 </typedef>
3854
3855 <typedef id="jvmtiHeapReferenceInfoJniLocal"
3856 label="Reference information structure for JNI local references"
3857 since="1.1">
3858 <description>
3859 Reference information returned for
3860 <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3861 </description>
3862 <field id="thread_tag">
3863 <jlong/>
3864 <description>
3865 The tag of the thread corresponding to this stack, zero if not tagged.
3866 </description>
3867 </field>
3868 <field id="thread_id">
3869 <jlong/>
3870 <description>
3871 The unique thread ID of the thread corresponding to this stack.
3872 </description>
3873 </field>
3874 <field id="depth">
3875 <jint/>
3876 <description>
3877 The depth of the frame.
3878 </description>
3879 </field>
3880 <field id="method">
3881 <jmethodID/>
3882 <description>
3883 The method executing in this frame.
3884 </description>
3885 </field>
3886 </typedef>
3887
3888 <typedef id="jvmtiHeapReferenceInfoReserved"
3889 label="Reference information structure for Other references"
3890 since="1.1">
3891 <description>
3892 Reference information returned for other references.
3893 </description>
3894 <field id="reserved1">
3895 <jlong/>
3896 <description>
3897 reserved for future use.
3898 </description>
3899 </field>
3900 <field id="reserved2">
3901 <jlong/>
3902 <description>
3903 reserved for future use.
3904 </description>
3905 </field>
3906 <field id="reserved3">
3907 <jlong/>
3908 <description>
3909 reserved for future use.
3910 </description>
3911 </field>
3912 <field id="reserved4">
3913 <jlong/>
3914 <description>
3915 reserved for future use.
3916 </description>
3917 </field>
3918 <field id="reserved5">
3919 <jlong/>
3920 <description>
3921 reserved for future use.
3922 </description>
3923 </field>
3924 <field id="reserved6">
3925 <jlong/>
3926 <description>
3927 reserved for future use.
3928 </description>
3929 </field>
3930 <field id="reserved7">
3931 <jlong/>
3932 <description>
3933 reserved for future use.
3934 </description>
3935 </field>
3936 <field id="reserved8">
3937 <jlong/>
3938 <description>
3939 reserved for future use.
3940 </description>
3941 </field>
3942 </typedef>
3943
3944 <uniontypedef id="jvmtiHeapReferenceInfo"
3945 label="Reference information structure"
3946 since="1.1">
3947 <description>
3948 The information returned about referrers.
3949 Represented as a union of the various kinds of reference information.
3950 </description>
3951 <field id="field">
3952 <struct>jvmtiHeapReferenceInfoField</struct>
3953 <description>
3954 The referrer information for
3955 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>
3956 and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3957 </description>
3958 </field>
3959 <field id="array">
3960 <struct>jvmtiHeapReferenceInfoArray</struct>
3961 <description>
3962 The referrer information for
3963 For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3964 </description>
3965 </field>
3966 <field id="constant_pool">
3967 <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3968 <description>
3969 The referrer information for
3970 For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3971 </description>
3972 </field>
3973 <field id="stack_local">
3974 <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3975 <description>
3976 The referrer information for
3977 For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3978 </description>
3979 </field>
3980 <field id="jni_local">
3981 <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3982 <description>
3983 The referrer information for
3984 For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3985 </description>
3986 </field>
3987 <field id="other">
3988 <struct>jvmtiHeapReferenceInfoReserved</struct>
3989 <description>
3990 reserved for future use.
3991 </description>
3992 </field>
3993 </uniontypedef>
3994
3995 <typedef id="jvmtiHeapCallbacks"
3996 label="Heap callback function structure"
3997 since="1.1">
3998 <field id="heap_iteration_callback">
3999 <ptrtype>
4000 <struct>jvmtiHeapIterationCallback</struct>
4001 </ptrtype>
4002 <description>
4003 The callback to be called to describe an
4004 object in the heap. Used by the
4005 <functionlink id="IterateThroughHeap"/> function, ignored by the
4006 <functionlink id="FollowReferences"/> function.
4007 </description>
4008 </field>
4009 <field id="heap_reference_callback">
4010 <ptrtype>
4011 <struct>jvmtiHeapReferenceCallback</struct>
4012 </ptrtype>
4013 <description>
4014 The callback to be called to describe an
4015 object reference. Used by the
4016 <functionlink id="FollowReferences"/> function, ignored by the
4017 <functionlink id="IterateThroughHeap"/> function.
4018 </description>
4019 </field>
4020 <field id="primitive_field_callback">
4021 <ptrtype>
4022 <struct>jvmtiPrimitiveFieldCallback</struct>
4023 </ptrtype>
4024 <description>
4025 The callback to be called to describe a
4026 primitive field.
4027 </description>
4028 </field>
4029 <field id="array_primitive_value_callback">
4030 <ptrtype>
4031 <struct>jvmtiArrayPrimitiveValueCallback</struct>
4032 </ptrtype>
4033 <description>
4034 The callback to be called to describe an
4035 array of primitive values.
4036 </description>
4037 </field>
4038 <field id="string_primitive_value_callback">
4039 <ptrtype>
4040 <struct>jvmtiStringPrimitiveValueCallback</struct>
4041 </ptrtype>
4042 <description>
4043 The callback to be called to describe a String value.
4044 </description>
4045 </field>
4046 <field id="reserved5">
4047 <ptrtype>
4048 <struct>jvmtiReservedCallback</struct>
4049 </ptrtype>
4050 <description>
4051 Reserved for future use..
4052 </description>
4053 </field>
4054 <field id="reserved6">
4055 <ptrtype>
4056 <struct>jvmtiReservedCallback</struct>
4057 </ptrtype>
4058 <description>
4059 Reserved for future use..
4060 </description>
4061 </field>
4062 <field id="reserved7">
4063 <ptrtype>
4064 <struct>jvmtiReservedCallback</struct>
4065 </ptrtype>
4066 <description>
4067 Reserved for future use..
4068 </description>
4069 </field>
4070 <field id="reserved8">
4071 <ptrtype>
4072 <struct>jvmtiReservedCallback</struct>
4073 </ptrtype>
4074 <description>
4075 Reserved for future use..
4076 </description>
4077 </field>
4078 <field id="reserved9">
4079 <ptrtype>
4080 <struct>jvmtiReservedCallback</struct>
4081 </ptrtype>
4082 <description>
4083 Reserved for future use..
4084 </description>
4085 </field>
4086 <field id="reserved10">
4087 <ptrtype>
4088 <struct>jvmtiReservedCallback</struct>
4089 </ptrtype>
4090 <description>
4091 Reserved for future use..
4092 </description>
4093 </field>
4094 <field id="reserved11">
4095 <ptrtype>
4096 <struct>jvmtiReservedCallback</struct>
4097 </ptrtype>
4098 <description>
4099 Reserved for future use..
4100 </description>
4101 </field>
4102 <field id="reserved12">
4103 <ptrtype>
4104 <struct>jvmtiReservedCallback</struct>
4105 </ptrtype>
4106 <description>
4107 Reserved for future use..
4108 </description>
4109 </field>
4110 <field id="reserved13">
4111 <ptrtype>
4112 <struct>jvmtiReservedCallback</struct>
4113 </ptrtype>
4114 <description>
4115 Reserved for future use..
4116 </description>
4117 </field>
4118 <field id="reserved14">
4119 <ptrtype>
4120 <struct>jvmtiReservedCallback</struct>
4121 </ptrtype>
4122 <description>
4123 Reserved for future use..
4124 </description>
4125 </field>
4126 <field id="reserved15">
4127 <ptrtype>
4128 <struct>jvmtiReservedCallback</struct>
4129 </ptrtype>
4130 <description>
4131 Reserved for future use..
4132 </description>
4133 </field>
4134 </typedef>
4135
4136
4137 <intro>
4138 <rationale>
4139 The heap dumping functionality (below) uses a callback
4140 for each object. While it would seem that a buffered approach
4141 would provide better throughput, tests do
4142 not show this to be the case--possibly due to locality of
4143 memory reference or array access overhead.
4144 </rationale>
4145
4146 <issue>
4147 Still under investigation as to if java.lang.ref references
4148 are reported as a different type of reference.
4149 </issue>
4150
4151 <issue>
4152 Should or can an indication of the cost or relative cost of
4153 these operations be included?
4154 </issue>
4155
4156 </intro>
4157
4158 <callback id="jvmtiHeapIterationCallback" since="1.1">
4159 <jint/>
4160 <synopsis>Heap Iteration Callback</synopsis>
4161 <description>
4162 Agent supplied callback function.
4163 Describes (but does not pass in) an object in the heap.
4164 <p/>
4165 This function should return a bit vector of the desired
4166 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4167 This will determine if the entire iteration should be aborted
4168 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4169 <p/>
4170 See the <internallink id="heapCallbacks">heap callback
4171 function restrictions</internallink>.
4172 </description>
4173 <parameters>
4174 <param id="class_tag">
4175 <jlong/>
4176 <description>
4177 The tag of the class of object (zero if the class is not tagged).
4178 If the object represents a runtime class,
4179 the <code>class_tag</code> is the tag
4180 associated with <code>java.lang.Class</code>
4181 (zero if <code>java.lang.Class</code> is not tagged).
4182 </description>
4183 </param>
4184 <param id="size">
4185 <jlong/>
4186 <description>
4187 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
4188 </description>
4189 </param>
4190 <param id="tag_ptr">
4191 <outptr><jlong/></outptr>
4192 <description>
4193 The object tag value, or zero if the object is not tagged.
4194 To set the tag value to be associated with the object
4195 the agent sets the <code>jlong</code> pointed to by the parameter.
4196 </description>
4197 </param>
4198 <param id="length">
4199 <jint/>
4200 <description>
4201 If this object is an array, the length of the array. Otherwise negative one (-1).
4202 </description>
4203 </param>
4204 <param id="user_data">
4205 <outptr><void/></outptr>
4206 <description>
4207 The user supplied data that was passed into the iteration function.
4208 </description>
4209 </param>
4210 </parameters>
4211 </callback>
4212
4213 <callback id="jvmtiHeapReferenceCallback" since="1.1">
4214 <jint/>
4215 <synopsis>Heap Reference Callback</synopsis>
4216 <description>
4217 Agent supplied callback function.
4218 Describes a reference from an object or the VM (the referrer) to another object
4219 (the referree) or a heap root to a referree.
4220 <p/>
4221 This function should return a bit vector of the desired
4222 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4223 This will determine if the objects referenced by the referree
4224 should be visited or if the entire iteration should be aborted.
4225 <p/>
4226 See the <internallink id="heapCallbacks">heap callback
4227 function restrictions</internallink>.
4228 </description>
4229 <parameters>
4230 <param id="reference_kind">
4231 <enum>jvmtiHeapReferenceKind</enum>
4232 <description>
4233 The kind of reference.
4234 </description>
4235 </param>
4236 <param id="reference_info">
4237 <inptr>
4238 <struct>jvmtiHeapReferenceInfo</struct>
4239 </inptr>
4240 <description>
4241 Details about the reference.
4242 Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4243 <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4244 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4245 <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4246 <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>,
4247 <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4248 or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4249 Otherwise <code>NULL</code>.
4250 </description>
4251 </param>
4252 <param id="class_tag">
4253 <jlong/>
4254 <description>
4255 The tag of the class of referree object (zero if the class is not tagged).
4256 If the referree object represents a runtime class,
4257 the <code>class_tag</code> is the tag
4258 associated with <code>java.lang.Class</code>
4259 (zero if <code>java.lang.Class</code> is not tagged).
4260 </description>
4261 </param>
4262 <param id="referrer_class_tag">
4263 <jlong/>
4264 <description>
4265 The tag of the class of the referrer object (zero if the class is not tagged
4266 or the referree is a heap root). If the referrer object represents a runtime
4267 class, the <code>referrer_class_tag</code> is the tag associated with
4268 the <code>java.lang.Class</code>
4269 (zero if <code>java.lang.Class</code> is not tagged).
4270 </description>
4271 </param>
4272 <param id="size">
4273 <jlong/>
4274 <description>
4275 Size of the referree object (in bytes).
4276 See <functionlink id="GetObjectSize"/>.
4277 </description>
4278 </param>
4279 <param id="tag_ptr">
4280 <outptr><jlong/></outptr>
4281 <description>
4282 Points to the referree object tag value, or zero if the object is not
4283 tagged.
4284 To set the tag value to be associated with the object
4285 the agent sets the <code>jlong</code> pointed to by the parameter.
4286 </description>
4287 </param>
4288 <param id="referrer_tag_ptr">
4289 <outptr><jlong/></outptr>
4290 <description>
4291 Points to the tag of the referrer object, or
4292 points to the zero if the referrer
4293 object is not tagged.
4294 <code>NULL</code> if the referrer in not an object (that is,
4295 this callback is reporting a heap root).
4296 To set the tag value to be associated with the referrer object
4297 the agent sets the <code>jlong</code> pointed to by the parameter.
4298 If this callback is reporting a reference from an object to itself,
4299 <code>referrer_tag_ptr == tag_ptr</code>.
4300 </description>
4301 </param>
4302 <param id="length">
4303 <jint/>
4304 <description>
4305 If this object is an array, the length of the array. Otherwise negative one (-1).
4306 </description>
4307 </param>
4308 <param id="user_data">
4309 <outptr><void/></outptr>
4310 <description>
4311 The user supplied data that was passed into the iteration function.
4312 </description>
4313 </param>
4314 </parameters>
4315 </callback>
4316
4317 <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4318 <jint/>
4319 <synopsis>Primitive Field Callback</synopsis>
4320 <description>
4321 Agent supplied callback function which
4322 describes a primitive field of an object (<i>the object</i>).
4323 A primitive field is a field whose type is a primitive type.
4324 This callback will describe a static field if the object is a class,
4325 and otherwise will describe an instance field.
4326 <p/>
4327 This function should return a bit vector of the desired
4328 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4329 This will determine if the entire iteration should be aborted
4330 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4331 <p/>
4332 See the <internallink id="heapCallbacks">heap callback
4333 function restrictions</internallink>.
4334 </description>
4335 <parameters>
4336 <param id="kind">
4337 <enum>jvmtiHeapReferenceKind</enum>
4338 <description>
4339 The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or
4340 <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4341 </description>
4342 </param>
4343 <param id="info">
4344 <inptr>
4345 <struct>jvmtiHeapReferenceInfo</struct>
4346 </inptr>
4347 <description>
4348 Which field (the field index).
4349 </description>
4350 </param>
4351 <param id="object_class_tag">
4352 <jlong/>
4353 <description>
4354 The tag of the class of the object (zero if the class is not tagged).
4355 If the object represents a runtime class, the
4356 <code>object_class_tag</code> is the tag
4357 associated with <code>java.lang.Class</code>
4358 (zero if <code>java.lang.Class</code> is not tagged).
4359 </description>
4360 </param>
4361 <param id="object_tag_ptr">
4362 <outptr><jlong/></outptr>
4363 <description>
4364 Points to the tag of the object, or zero if the object is not
4365 tagged.
4366 To set the tag value to be associated with the object
4367 the agent sets the <code>jlong</code> pointed to by the parameter.
4368 </description>
4369 </param>
4370 <param id="value">
4371 <jvalue/>
4372 <description>
4373 The value of the field.
4374 </description>
4375 </param>
4376 <param id="value_type">
4377 <enum>jvmtiPrimitiveType</enum>
4378 <description>
4379 The type of the field.
4380 </description>
4381 </param>
4382 <param id="user_data">
4383 <outptr><void/></outptr>
4384 <description>
4385 The user supplied data that was passed into the iteration function.
4386 </description>
4387 </param>
4388 </parameters>
4389 </callback>
4390
4391 <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4392 <jint/>
4393 <synopsis>Array Primitive Value Callback</synopsis>
4394 <description>
4395 Agent supplied callback function.
4396 Describes the values in an array of a primitive type.
4397 <p/>
4398 This function should return a bit vector of the desired
4399 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4400 This will determine if the entire iteration should be aborted
4401 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4402 <p/>
4403 See the <internallink id="heapCallbacks">heap callback
4404 function restrictions</internallink>.
4405 </description>
4406 <parameters>
4407 <param id="class_tag">
4408 <jlong/>
4409 <description>
4410 The tag of the class of the array object (zero if the class is not tagged).
4411 </description>
4412 </param>
4413 <param id="size">
4414 <jlong/>
4415 <description>
4416 Size of the array (in bytes).
4417 See <functionlink id="GetObjectSize"/>.
4418 </description>
4419 </param>
4420 <param id="tag_ptr">
4421 <outptr><jlong/></outptr>
4422 <description>
4423 Points to the tag of the array object, or zero if the object is not
4424 tagged.
4425 To set the tag value to be associated with the object
4426 the agent sets the <code>jlong</code> pointed to by the parameter.
4427 </description>
4428 </param>
4429 <param id="element_count">
4430 <jint/>
4431 <description>
4432 The length of the primitive array.
4433 </description>
4434 </param>
4435 <param id="element_type">
4436 <enum>jvmtiPrimitiveType</enum>
4437 <description>
4438 The type of the elements of the array.
4439 </description>
4440 </param>
4441 <param id="elements">
4442 <vmbuf><void/></vmbuf>
4443 <description>
4444 The elements of the array in a packed array of <code>element_count</code>
4445 items of <code>element_type</code> size each.
4446 </description>
4447 </param>
4448 <param id="user_data">
4449 <outptr><void/></outptr>
4450 <description>
4451 The user supplied data that was passed into the iteration function.
4452 </description>
4453 </param>
4454 </parameters>
4455 </callback>
4456
4457 <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4458 <jint/>
4459 <synopsis>String Primitive Value Callback</synopsis>
4460 <description>
4461 Agent supplied callback function.
4462 Describes the value of a java.lang.String.
4463 <p/>
4464 This function should return a bit vector of the desired
4465 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4466 This will determine if the entire iteration should be aborted
4467 (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4468 <p/>
4469 See the <internallink id="heapCallbacks">heap callback
4470 function restrictions</internallink>.
4471 </description>
4472 <parameters>
4473 <param id="class_tag">
4474 <jlong/>
4475 <description>
4476 The tag of the class of the String class (zero if the class is not tagged).
4477 <issue>Is this needed?</issue>
4478 </description>
4479 </param>
4480 <param id="size">
4481 <jlong/>
4482 <description>
4483 Size of the string (in bytes).
4484 See <functionlink id="GetObjectSize"/>.
4485 </description>
4486 </param>
4487 <param id="tag_ptr">
4488 <outptr><jlong/></outptr>
4489 <description>
4490 Points to the tag of the String object, or zero if the object is not
4491 tagged.
4492 To set the tag value to be associated with the object
4493 the agent sets the <code>jlong</code> pointed to by the parameter.
4494 </description>
4495 </param>
4496 <param id="value">
4497 <vmbuf><jchar/></vmbuf>
4498 <description>
4499 The value of the String, encoded as a Unicode string.
4500 </description>
4501 </param>
4502 <param id="value_length">
4503 <jint/>
4504 <description>
4505 The length of the string.
4506 The length is equal to the number of 16-bit Unicode
4507 characters in the string.
4508 </description>
4509 </param>
4510 <param id="user_data">
4511 <outptr><void/></outptr>
4512 <description>
4513 The user supplied data that was passed into the iteration function.
4514 </description>
4515 </param>
4516 </parameters>
4517 </callback>
4518
4519
4520 <callback id="jvmtiReservedCallback" since="1.1">
4521 <jint/>
4522 <synopsis>reserved for future use Callback</synopsis>
4523 <description>
4524 Placeholder -- reserved for future use.
4525 </description>
4526 <parameters>
4527 </parameters>
4528 </callback>
4529
4530 <function id="FollowReferences" num="115" since="1.1">
4531 <synopsis>Follow References</synopsis>
4532 <description>
4533 This function initiates a traversal over the objects that are
4534 directly and indirectly reachable from the specified object or,
4535 if <code>initial_object</code> is not specified, all objects
4536 reachable from the heap roots.
4537 The heap root are the set of system classes,
4538 JNI globals, references from thread stacks, and other objects used as roots
4539 for the purposes of garbage collection.
4540 <p/>
4541 This function operates by traversing the reference graph.
4542 Let <i>A</i>, <i>B</i>, ... represent objects.
4543 When a reference from <i>A</i> to <i>B</i> is traversed,
4544 when a reference from a heap root to <i>B</i> is traversed,
4545 or when <i>B</i> is specified as the <paramlink id="initial_object"/>,
4546 then <i>B</i> is said to be <i>visited</i>.
4547 A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i>
4548 is visited.
4549 References are reported in the same order that the references are traversed.
4550 Object references are reported by invoking the agent supplied
4551 callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4552 In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known
4553 as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4554 The callback is invoked exactly once for each reference from a referrer;
4555 this is true even if there are reference cycles or multiple paths to
4556 the referrer.
4557 There may be more than one reference between a referrer and a referree,
4558 each reference is reported.
4559 These references may be distinguished by examining the
4560 <datalink
4561 id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4562 and
4563 <datalink
4564 id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4565 parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4566 <p/>
4567 This function reports a Java programming language view of object references,
4568 not a virtual machine implementation view. The following object references
4569 are reported when they are non-null:
4570 <ul>
4571 <li>Instance objects report references to each non-primitive instance fields
4572 (including inherited fields).</li>
4573 <li>Instance objects report a reference to the object type (class).</li>
4574 <li>Classes report a reference to the superclass and directly
4575 implemented/extended interfaces.</li>
4576 <li>Classes report a reference to the class loader, protection domain,
4577 signers, and resolved entries in the constant pool.</li>
4578 <li>Classes report a reference to each directly declared non-primitive
4579 static field.</li>
4580 <li>Arrays report a reference to the array type (class) and each
4581 array element.</li>
4582 <li>Primitive arrays report a reference to the array type.</li>
4583 </ul>
4584 <p/>
4585 This function can also be used to examine primitive (non-object) values.
4586 The primitive value of an array or String
4587 is reported after the object has been visited;
4588 it is reported by invoking the agent supplied callback function
4589 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4590 <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4591 A primitive field
4592 is reported after the object with that field is visited;
4593 it is reported by invoking the agent supplied callback function
4594 <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4595 <p/>
4596 Whether a callback is provided or is <code>NULL</code> only determines
4597 whether the callback will be invoked, it does not influence
4598 which objects are visited nor does it influence whether other callbacks
4599 will be invoked.
4600 However, the
4601 <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4602 returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4603 do determine if the objects referenced by the
4604 current object as visited.
4605 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4606 and <paramlink id="klass"/> provided as parameters to this function
4607 do not control which objects are visited but they do control which
4608 objects and primitive values are reported by the callbacks.
4609 For example, if the only callback that was set is
4610 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4611 is set to the array of bytes class, then only arrays of byte will be
4612 reported.
4613 The table below summarizes this:
4614 <p/>
4615 <table>
4616 <tr class="bgLight">
4617 <th/>
4618 <th class="centered" scope="col">Controls objects visited</th>
4619 <th class="centered" scope="col">Controls objects reported</th>
4620 <th class="centered" scope="col">Controls primitives reported</th>
4621 </tr>
4622 <tr>
4623 <th scope="row">
4624 the
4625 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4626 returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4627 </th>
4628 <td class="centered">
4629 <b>Yes</b>
4630 </td>
4631 <td class="centered">
4632 <b>Yes</b>, since visits are controlled
4633 </td>
4634 <td class="centered">
4635 <b>Yes</b>, since visits are controlled
4636 </td>
4637 </tr>
4638 <tr>
4639 <th scope="row">
4640 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4641 in <paramlink id="callbacks"/> set
4642 </th>
4643 <td class="centered">
4644 No
4645 </td>
4646 <td class="centered">
4647 <b>Yes</b>
4648 </td>
4649 <td class="centered">
4650 No
4651 </td>
4652 </tr>
4653 <tr>
4654 <th scope="row">
4655 <paramlink id="heap_filter"/>
4656 </th>
4657 <td class="centered">
4658 No
4659 </td>
4660 <td class="centered">
4661 <b>Yes</b>
4662 </td>
4663 <td class="centered">
4664 <b>Yes</b>
4665 </td>
4666 </tr>
4667 <tr>
4668 <th scope="row">
4669 <paramlink id="klass"/>
4670 </th>
4671 <td class="centered">
4672 No
4673 </td>
4674 <td class="centered">
4675 <b>Yes</b>
4676 </td>
4677 <td class="centered">
4678 <b>Yes</b>
4679 </td>
4680 </tr>
4681 </table>
4682 <p/>
4683 During the execution of this function the state of the heap
4684 does not change: no objects are allocated, no objects are
4685 garbage collected, and the state of objects (including
4686 held values) does not change.
4687 As a result, threads executing Java
4688 programming language code, threads attempting to resume the
4689 execution of Java programming language code, and threads
4690 attempting to execute JNI functions are typically stalled.
4691 </description>
4692 <origin>new</origin>
4693 <capabilities>
4694 <required id="can_tag_objects"></required>
4695 </capabilities>
4696 <parameters>
4697 <param id="heap_filter">
4698 <jint/>
4699 <description>
4700 This bit vector of
4701 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4702 restricts the objects for which the callback function is called.
4703 This applies to both the object and primitive callbacks.
4704 </description>
4705 </param>
4706 <param id="klass">
4707 <ptrtype>
4708 <jclass/>
4709 <nullok>callbacks are not limited to instances of a particular
4710 class</nullok>
4711 </ptrtype>
4712 <description>
4713 Callbacks are only reported when the object is an instance of
4714 this class.
4715 Objects which are instances of a subclass of <code>klass</code>
4716 are not reported.
4717 If <code>klass</code> is an interface, no objects are reported.
4718 This applies to both the object and primitive callbacks.
4719 </description>
4720 </param>
4721 <param id="initial_object">
4722 <ptrtype>
4723 <jobject/>
4724 <nullok>references are followed from the heap roots</nullok>
4725 </ptrtype>
4726 <description>
4727 The object to follow
4728 </description>
4729 </param>
4730 <param id="callbacks">
4731 <inptr>
4732 <struct>jvmtiHeapCallbacks</struct>
4733 </inptr>
4734 <description>
4735 Structure defining the set of callback functions.
4736 </description>
4737 </param>
4738 <param id="user_data">
4739 <inbuf>
4740 <void/>
4741 <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4742 </inbuf>
4743 <description>
4744 User supplied data to be passed to the callback.
4745 </description>
4746 </param>
4747 </parameters>
4748 <errors>
4749 <error id="JVMTI_ERROR_INVALID_CLASS">
4750 <paramlink id="klass"/> is not a valid class.
4751 </error>
4752 <error id="JVMTI_ERROR_INVALID_OBJECT">
4753 <paramlink id="initial_object"/> is not a valid object.
4754 </error>
4755 </errors>
4756 </function>
4757
4758
4759 <function id="IterateThroughHeap" num="116" since="1.1">
4760 <synopsis>Iterate Through Heap</synopsis>
4761 <description>
4762 Initiate an iteration over all objects in the heap.
4763 This includes both reachable and
4764 unreachable objects. Objects are visited in no particular order.
4765 <p/>
4766 Heap objects are reported by invoking the agent supplied
4767 callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4768 References between objects are not reported.
4769 If only reachable objects are desired, or if object reference information
4770 is needed, use <functionlink id="FollowReferences"/>.
4771 <p/>
4772 This function can also be used to examine primitive (non-object) values.
4773 The primitive value of an array or String
4774 is reported after the object has been visited;
4775 it is reported by invoking the agent supplied callback function
4776 <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4777 <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4778 A primitive field
4779 is reported after the object with that field is visited;
4780 it is reported by invoking the agent supplied
4781 callback function
4782 <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4783 <p/>
4784 Unless the iteration is aborted by the
4785 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4786 returned by a callback, all objects in the heap are visited.
4787 Whether a callback is provided or is <code>NULL</code> only determines
4788 whether the callback will be invoked, it does not influence
4789 which objects are visited nor does it influence whether other callbacks
4790 will be invoked.
4791 The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4792 and <paramlink id="klass"/> provided as parameters to this function
4793 do not control which objects are visited but they do control which
4794 objects and primitive values are reported by the callbacks.
4795 For example, if the only callback that was set is
4796 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4797 is set to the array of bytes class, then only arrays of byte will be
4798 reported. The table below summarizes this (contrast this with
4799 <functionlink id="FollowReferences"/>):
4800 <p/>
4801 <table>
4802 <tr class="bgLight">
4803 <th/>
4804 <th class="centered" scope="col">Controls objects visited</th>
4805 <th class="centered" scope="col">Controls objects reported</th>
4806 <th class="centered" scope="col">Controls primitives reported</th>
4807 </tr>
4808 <tr>
4809 <th scope="row">
4810 the
4811 <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4812 returned by <functionlink id="jvmtiHeapIterationCallback"/>
4813 </th>
4814 <td class="centered">
4815 No<br/>(unless they abort the iteration)
4816 </td>
4817 <td class="centered">
4818 No<br/>(unless they abort the iteration)
4819 </td>
4820 <td class="centered">
4821 No<br/>(unless they abort the iteration)
4822 </td>
4823 </tr>
4824 <tr>
4825 <th scope="row">
4826 <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4827 in <paramlink id="callbacks"/> set
4828 </th>
4829 <td class="centered">
4830 No
4831 </td>
4832 <td class="centered">
4833 <b>Yes</b>
4834 </td>
4835 <td class="centered">
4836 No
4837 </td>
4838 </tr>
4839 <tr>
4840 <th scope="row">
4841 <paramlink id="heap_filter"/>
4842 </th>
4843 <td class="centered">
4844 No
4845 </td>
4846 <td class="centered">
4847 <b>Yes</b>
4848 </td>
4849 <td class="centered">
4850 <b>Yes</b>
4851 </td>
4852 </tr>
4853 <tr>
4854 <th scope="row">
4855 <paramlink id="klass"/>
4856 </th>
4857 <td class="centered">
4858 No
4859 </td>
4860 <td class="centered">
4861 <b>Yes</b>
4862 </td>
4863 <td class="centered">
4864 <b>Yes</b>
4865 </td>
4866 </tr>
4867 </table>
4868 <p/>
4869 During the execution of this function the state of the heap
4870 does not change: no objects are allocated, no objects are
4871 garbage collected, and the state of objects (including
4872 held values) does not change.
4873 As a result, threads executing Java
4874 programming language code, threads attempting to resume the
4875 execution of Java programming language code, and threads
4876 attempting to execute JNI functions are typically stalled.
4877 </description>
4878 <origin>new</origin>
4879 <capabilities>
4880 <required id="can_tag_objects"></required>
4881 </capabilities>
4882 <parameters>
4883 <param id="heap_filter">
4884 <jint/>
4885 <description>
4886 This bit vector of
4887 <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4888 restricts the objects for which the callback function is called.
4889 This applies to both the object and primitive callbacks.
4890 </description>
4891 </param>
4892 <param id="klass">
4893 <ptrtype>
4894 <jclass/>
4895 <nullok>callbacks are not limited to instances of a particular class</nullok>
4896 </ptrtype>
4897 <description>
4898 Callbacks are only reported when the object is an instance of
4899 this class.
4900 Objects which are instances of a subclass of <code>klass</code>
4901 are not reported.
4902 If <code>klass</code> is an interface, no objects are reported.
4903 This applies to both the object and primitive callbacks.
4904 </description>
4905 </param>
4906 <param id="callbacks">
4907 <inptr>
4908 <struct>jvmtiHeapCallbacks</struct>
4909 </inptr>
4910 <description>
4911 Structure defining the set callback functions.
4912 </description>
4913 </param>
4914 <param id="user_data">
4915 <inbuf>
4916 <void/>
4917 <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4918 </inbuf>
4919 <description>
4920 User supplied data to be passed to the callback.
4921 </description>
4922 </param>
4923 </parameters>
4924 <errors>
4925 <error id="JVMTI_ERROR_INVALID_CLASS">
4926 <paramlink id="klass"/> is not a valid class.
4927 </error>
4928 </errors>
4929 </function>
4930
4931 <function id="GetTag" phase="start" num="106">
4932 <synopsis>Get Tag</synopsis>
4933 <description>
4934 Retrieve the tag associated with an object.
4935 The tag is a long value typically used to store a
4936 unique identifier or pointer to object information.
4937 The tag is set with
4938 <functionlink id="SetTag"></functionlink>.
4939 Objects for which no tags have been set return a
4940 tag value of zero.
4941 </description>
4942 <origin>new</origin>
4943 <capabilities>
4944 <required id="can_tag_objects"></required>
4945 </capabilities>
4946 <parameters>
4947 <param id="object">
4948 <jobject/>
4949 <description>
4950 The object whose tag is to be retrieved.
4951 </description>
4952 </param>
4953 <param id="tag_ptr">
4954 <outptr><jlong/></outptr>
4955 <description>
4956 On return, the referenced long is set to the value
4957 of the tag.
4958 </description>
4959 </param>
4960 </parameters>
4961 <errors>
4962 </errors>
4963 </function>
4964
4965 <function id="SetTag" phase="start" num="107">
4966 <synopsis>Set Tag</synopsis>
4967 <description>
4968 Set the tag associated with an object.
4969 The tag is a long value typically used to store a
4970 unique identifier or pointer to object information.
4971 The tag is visible with
4972 <functionlink id="GetTag"></functionlink>.
4973 </description>
4974 <origin>new</origin>
4975 <capabilities>
4976 <required id="can_tag_objects"></required>
4977 </capabilities>
4978 <parameters>
4979 <param id="object">
4980 <jobject/>
4981 <description>
4982 The object whose tag is to be set.
4983 </description>
4984 </param>
4985 <param id="tag">
4986 <jlong/>
4987 <description>
4988 The new value of the tag.
4989 </description>
4990 </param>
4991 </parameters>
4992 <errors>
4993 </errors>
4994 </function>
4995
4996 <function id="GetObjectsWithTags" num="114">
4997 <synopsis>Get Objects With Tags</synopsis>
4998 <description>
4999 Return objects in the heap with the specified tags.
5000 The format is parallel arrays of objects and tags.
5001 </description>
5002 <origin>new</origin>
5003 <capabilities>
5004 <required id="can_tag_objects"></required>
5005 </capabilities>
5006 <parameters>
5007 <param id="tag_count">
5008 <jint min="0"/>
5009 <description>
5010 Number of tags to scan for.
5011 </description>
5012 </param>
5013 <param id="tags">
5014 <inbuf incount="tag_count">
5015 <jlong/>
5016 </inbuf>
5017 <description>
5018 Scan for objects with these tags.
5019 Zero is not permitted in this array.
5020 </description>
5021 </param>
5022 <param id="count_ptr">
5023 <outptr>
5024 <jint/>
5025 </outptr>
5026 <description>
5027 Return the number of objects with any of the tags
5028 in <paramlink id="tags"/>.
5029 </description>
5030 </param>
5031 <param id="object_result_ptr">
5032 <allocbuf outcount="count_ptr">
5033 <jobject/>
5034 <nullok>this information is not returned</nullok>
5035 </allocbuf>
5036 <description>
5037 Returns the array of objects with any of the tags
5038 in <paramlink id="tags"/>.
5039 </description>
5040 </param>
5041 <param id="tag_result_ptr">
5042 <allocbuf outcount="count_ptr">
5043 <jlong/>
5044 <nullok>this information is not returned</nullok>
5045 </allocbuf>
5046 <description>
5047 For each object in <paramlink id="object_result_ptr"/>,
5048 return the tag at the corresponding index.
5049 </description>
5050 </param>
5051 </parameters>
5052 <errors>
5053 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
5054 Zero is present in <paramlink id="tags"></paramlink>.
5055 </error>
5056 </errors>
5057 </function>
5058
5059 <function id="ForceGarbageCollection" num="108">
5060 <synopsis>Force Garbage Collection</synopsis>
5061 <description>
5062 Force the VM to perform a garbage collection.
5063 The garbage collection is as complete as possible.
5064 This function does not cause finalizers to be run.
5065 This function does not return until the garbage collection
5066 is finished.
5067 <p/>
5068 Although garbage collection is as complete
5069 as possible there is no guarantee that all
5070 <eventlink id="ObjectFree"/>
5071 events will have been
5072 sent by the time that this function
5073 returns. In particular, an object may be
5074 prevented from being freed because it
5075 is awaiting finalization.
5076 </description>
5077 <origin>new</origin>
5078 <capabilities>
5079 </capabilities>
5080 <parameters>
5081 </parameters>
5082 <errors>
5083 </errors>
5084 </function>
5085
5086
5087 </category>
5088
5089 <category id="Heap_1_0" label="Heap (1.0)">
5090 <intro>
5091 <b>
5092 These functions and data types were introduced in the original
5093 <jvmti/> version 1.0. They are deprecated and will be changed
5094 to return an error in a future release. They were superseded in
5095 <jvmti/> version 1.2 (Java SE 6) by more
5096 </b>
5097 <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
5098 <b>
5099 which:
5100 </b>
5101 <ul>
5102 <li>
5103 <b>
5104 Allow access to primitive values (the value of Strings, arrays,
5105 and primitive fields)
5106 </b>
5107 </li>
5108 <li>
5109 <b>
5110 Allow the tag of the referrer to be set, thus enabling more
5111 efficient localized reference graph building
5112 </b>
5113 </li>
5114 <li>
5115 <b>
5116 Provide more extensive filtering abilities
5117 </b>
5118 </li>
5119 <li>
5120 <b>
5121 Are extensible, allowing their abilities to grow in future versions of <jvmti/>
5122 </b>
5123 </li>
5124 </ul>
5125 <p/>
5126 <b>Please use the </b>
5127 <internallink id="Heap"><b>current Heap functions</b></internallink>.
5128 <p/>
5129 <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
5130 <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
5131 Tagged objects only.
5132 </constant>
5133 <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
5134 Untagged objects only.
5135 </constant>
5136 <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
5137 Either tagged or untagged objects.
5138 </constant>
5139 </constants>
5140
5141 <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
5142 <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
5143 JNI global reference.
5144 </constant>
5145 <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
5146 System class.
5147 </constant>
5148 <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
5149 Monitor.
5150 </constant>
5151 <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
5152 Stack local.
5153 </constant>
5154 <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
5155 JNI local reference.
5156 </constant>
5157 <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
5158 Thread.
5159 </constant>
5160 <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
5161 Other.
5162 </constant>
5163 </constants>
5164
5165 <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
5166 <constant id="JVMTI_REFERENCE_CLASS" num="1">
5167 Reference from an object to its class.
5168 </constant>
5169 <constant id="JVMTI_REFERENCE_FIELD" num="2">
5170 Reference from an object to the value of one of its instance fields.
5171 For references of this kind the <code>referrer_index</code>
5172 parameter to the <internallink id="jvmtiObjectReferenceCallback">
5173 jvmtiObjectReferenceCallback</internallink> is the index of the
5174 the instance field. The index is based on the order of all the
5175 object's fields. This includes all fields of the directly declared
5176 static and instance fields in the class, and includes all fields (both
5177 public and private) fields declared in superclasses and superinterfaces.
5178 The index is thus calculated by summing the index of the field in the directly
5179 declared class (see <functionlink id="GetClassFields"/>), with the total
5180 number of fields (both public and private) declared in all superclasses
5181 and superinterfaces. The index starts at zero.
5182 </constant>
5183 <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
5184 Reference from an array to one of its elements.
5185 For references of this kind the <code>referrer_index</code>
5186 parameter to the <internallink id="jvmtiObjectReferenceCallback">
5187 jvmtiObjectReferenceCallback</internallink> is the array index.
5188 </constant>
5189 <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
5190 Reference from a class to its class loader.
5191 </constant>
5192 <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
5193 Reference from a class to its signers array.
5194 </constant>
5195 <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
5196 Reference from a class to its protection domain.
5197 </constant>
5198 <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
5199 Reference from a class to one of its interfaces.
5200 </constant>
5201 <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
5202 Reference from a class to the value of one of its static fields.
5203 For references of this kind the <code>referrer_index</code>
5204 parameter to the <internallink id="jvmtiObjectReferenceCallback">
5205 jvmtiObjectReferenceCallback</internallink> is the index of the
5206 the static field. The index is based on the order of all the
5207 object's fields. This includes all fields of the directly declared
5208 static and instance fields in the class, and includes all fields (both
5209 public and private) fields declared in superclasses and superinterfaces.
5210 The index is thus calculated by summing the index of the field in the directly
5211 declared class (see <functionlink id="GetClassFields"/>), with the total
5212 number of fields (both public and private) declared in all superclasses
5213 and superinterfaces. The index starts at zero.
5214 Note: this definition differs from that in the <jvmti/> 1.0 Specification.
5215 <rationale>No known implementations used the 1.0 definition.</rationale>
5216 </constant>
5217 <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
5218 Reference from a class to a resolved entry in the constant pool.
5219 For references of this kind the <code>referrer_index</code>
5220 parameter to the <internallink id="jvmtiObjectReferenceCallback">
5221 jvmtiObjectReferenceCallback</internallink> is the index into
5222 constant pool table of the class, starting at 1. See
5223 <vmspec chapter="4.4"/>.
5224 </constant>
5225 </constants>
5226
5227 <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5228 <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5229 Continue the iteration.
5230 If this is a reference iteration, follow the references of this object.
5231 </constant>
5232 <constant id="JVMTI_ITERATION_IGNORE" num="2">
5233 Continue the iteration.
5234 If this is a reference iteration, ignore the references of this object.
5235 </constant>
5236 <constant id="JVMTI_ITERATION_ABORT" num="0">
5237 Abort the iteration.
5238 </constant>
5239 </constants>
5240 </intro>
5241
5242 <callback id="jvmtiHeapObjectCallback">
5243 <enum>jvmtiIterationControl</enum>
5244 <synopsis>Heap Object Callback</synopsis>
5245 <description>
5246 Agent supplied callback function.
5247 Describes (but does not pass in) an object in the heap.
5248 <p/>
5249 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5250 or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5251 <p/>
5252 See the <internallink id="heapCallbacks">heap callback
5253 function restrictions</internallink>.
5254 </description>
5255 <parameters>
5256 <param id="class_tag">
5257 <jlong/>
5258 <description>
5259 The tag of the class of object (zero if the class is not tagged).
5260 If the object represents a runtime class,
5261 the <code>class_tag</code> is the tag
5262 associated with <code>java.lang.Class</code>
5263 (zero if <code>java.lang.Class</code> is not tagged).
5264 </description>
5265 </param>
5266 <param id="size">
5267 <jlong/>
5268 <description>
5269 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5270 </description>
5271 </param>
5272 <param id="tag_ptr">
5273 <outptr><jlong/></outptr>
5274 <description>
5275 The object tag value, or zero if the object is not tagged.
5276 To set the tag value to be associated with the object
5277 the agent sets the <code>jlong</code> pointed to by the parameter.
5278 </description>
5279 </param>
5280 <param id="user_data">
5281 <outptr><void/></outptr>
5282 <description>
5283 The user supplied data that was passed into the iteration function.
5284 </description>
5285 </param>
5286 </parameters>
5287 </callback>
5288
5289 <callback id="jvmtiHeapRootCallback">
5290 <enum>jvmtiIterationControl</enum>
5291 <synopsis>Heap Root Object Callback</synopsis>
5292 <description>
5293 Agent supplied callback function.
5294 Describes (but does not pass in) an object that is a root for the purposes
5295 of garbage collection.
5296 <p/>
5297 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5298 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5299 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5300 <p/>
5301 See the <internallink id="heapCallbacks">heap callback
5302 function restrictions</internallink>.
5303 </description>
5304 <parameters>
5305 <param id="root_kind">
5306 <enum>jvmtiHeapRootKind</enum>
5307 <description>
5308 The kind of heap root.
5309 </description>
5310 </param>
5311 <param id="class_tag">
5312 <jlong/>
5313 <description>
5314 The tag of the class of object (zero if the class is not tagged).
5315 If the object represents a runtime class, the <code>class_tag</code> is the tag
5316 associated with <code>java.lang.Class</code>
5317 (zero if <code>java.lang.Class</code> is not tagged).
5318 </description>
5319 </param>
5320 <param id="size">
5321 <jlong/>
5322 <description>
5323 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5324 </description>
5325 </param>
5326 <param id="tag_ptr">
5327 <outptr><jlong/></outptr>
5328 <description>
5329 The object tag value, or zero if the object is not tagged.
5330 To set the tag value to be associated with the object
5331 the agent sets the <code>jlong</code> pointed to by the parameter.
5332 </description>
5333 </param>
5334 <param id="user_data">
5335 <outptr><void/></outptr>
5336 <description>
5337 The user supplied data that was passed into the iteration function.
5338 </description>
5339 </param>
5340 </parameters>
5341 </callback>
5342
5343 <callback id="jvmtiStackReferenceCallback">
5344 <enum>jvmtiIterationControl</enum>
5345 <synopsis>Stack Reference Object Callback</synopsis>
5346 <description>
5347 Agent supplied callback function.
5348 Describes (but does not pass in) an object on the stack that is a root for
5349 the purposes of garbage collection.
5350 <p/>
5351 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5352 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5353 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5354 <p/>
5355 See the <internallink id="heapCallbacks">heap callback
5356 function restrictions</internallink>.
5357 </description>
5358 <parameters>
5359 <param id="root_kind">
5360 <enum>jvmtiHeapRootKind</enum>
5361 <description>
5362 The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5363 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5364 </description>
5365 </param>
5366 <param id="class_tag">
5367 <jlong/>
5368 <description>
5369 The tag of the class of object (zero if the class is not tagged).
5370 If the object represents a runtime class, the <code>class_tag</code> is the tag
5371 associated with <code>java.lang.Class</code>
5372 (zero if <code>java.lang.Class</code> is not tagged).
5373 </description>
5374 </param>
5375 <param id="size">
5376 <jlong/>
5377 <description>
5378 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5379 </description>
5380 </param>
5381 <param id="tag_ptr">
5382 <outptr><jlong/></outptr>
5383 <description>
5384 The object tag value, or zero if the object is not tagged.
5385 To set the tag value to be associated with the object
5386 the agent sets the <code>jlong</code> pointed to by the parameter.
5387 </description>
5388 </param>
5389 <param id="thread_tag">
5390 <jlong/>
5391 <description>
5392 The tag of the thread corresponding to this stack, zero if not tagged.
5393 </description>
5394 </param>
5395 <param id="depth">
5396 <jint/>
5397 <description>
5398 The depth of the frame.
5399 </description>
5400 </param>
5401 <param id="method">
5402 <jmethodID/>
5403 <description>
5404 The method executing in this frame.
5405 </description>
5406 </param>
5407 <param id="slot">
5408 <jint/>
5409 <description>
5410 The slot number.
5411 </description>
5412 </param>
5413 <param id="user_data">
5414 <outptr><void/></outptr>
5415 <description>
5416 The user supplied data that was passed into the iteration function.
5417 </description>
5418 </param>
5419 </parameters>
5420 </callback>
5421
5422 <callback id="jvmtiObjectReferenceCallback">
5423 <enum>jvmtiIterationControl</enum>
5424 <synopsis>Object Reference Callback</synopsis>
5425 <description>
5426 Agent supplied callback function.
5427 Describes a reference from an object (the referrer) to another object
5428 (the referree).
5429 <p/>
5430 Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5431 <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5432 references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5433 <p/>
5434 See the <internallink id="heapCallbacks">heap callback
5435 function restrictions</internallink>.
5436 </description>
5437 <parameters>
5438 <param id="reference_kind">
5439 <enum>jvmtiObjectReferenceKind</enum>
5440 <description>
5441 The type of reference.
5442 </description>
5443 </param>
5444 <param id="class_tag">
5445 <jlong/>
5446 <description>
5447 The tag of the class of referree object (zero if the class is not tagged).
5448 If the referree object represents a runtime class,
5449 the <code>class_tag</code> is the tag
5450 associated with <code>java.lang.Class</code>
5451 (zero if <code>java.lang.Class</code> is not tagged).
5452 </description>
5453 </param>
5454 <param id="size">
5455 <jlong/>
5456 <description>
5457 Size of the referree object (in bytes).
5458 See <functionlink id="GetObjectSize"/>.
5459 </description>
5460 </param>
5461 <param id="tag_ptr">
5462 <outptr><jlong/></outptr>
5463 <description>
5464 The referree object tag value, or zero if the object is not
5465 tagged.
5466 To set the tag value to be associated with the object
5467 the agent sets the <code>jlong</code> pointed to by the parameter.
5468 </description>
5469 </param>
5470 <param id="referrer_tag">
5471 <jlong/>
5472 <description>
5473 The tag of the referrer object, or zero if the referrer
5474 object is not tagged.
5475 </description>
5476 </param>
5477 <param id="referrer_index">
5478 <jint/>
5479 <description>
5480 For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5481 <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5482 of the field in the referrer object. The index is based on the
5483 order of all the object's fields - see <internallink
5484 id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5485 or <internallink
5486 id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5487 </internallink> for further description.
5488 <p/>
5489 For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5490 the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5491 JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5492 <p/>
5493 For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5494 the index into the constant pool of the class - see
5495 <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5496 JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further
5497 description.
5498 <p/>
5499 For references of other kinds the <code>referrer_index</code> is
5500 <code>-1</code>.
5501 </description>
5502 </param>
5503 <param id="user_data">
5504 <outptr><void/></outptr>
5505 <description>
5506 The user supplied data that was passed into the iteration function.
5507 </description>
5508 </param>
5509 </parameters>
5510 </callback>
5511
5512 <function id="IterateOverObjectsReachableFromObject" num="109">
5513 <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5514 <description>
5515 This function iterates over all objects that are directly
5516 and indirectly reachable from the specified object.
5517 For each object <i>A</i> (known
5518 as the referrer) with a reference to object <i>B</i> the specified
5519 callback function is called to describe the object reference.
5520 The callback is called exactly once for each reference from a referrer;
5521 this is true even if there are reference cycles or multiple paths to
5522 the referrer.
5523 There may be more than one reference between a referrer and a referree,
5524 These may be distinguished by the
5525 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5526 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5527 The callback for an object will always occur after the callback for
5528 its referrer.
5529 <p/>
5530 See <functionlink id="FollowReferences"/> for the object
5531 references which are reported.
5532 <p/>
5533 During the execution of this function the state of the heap
5534 does not change: no objects are allocated, no objects are
5535 garbage collected, and the state of objects (including
5536 held values) does not change.
5537 As a result, threads executing Java
5538 programming language code, threads attempting to resume the
5539 execution of Java programming language code, and threads
5540 attempting to execute JNI functions are typically stalled.
5541 </description>
5542 <origin>new</origin>
5543 <capabilities>
5544 <required id="can_tag_objects"></required>
5545 </capabilities>
5546 <parameters>
5547 <param id="object">
5548 <jobject/>
5549 <description>
5550 The object
5551 </description>
5552 </param>
5553 <param id="object_reference_callback">
5554 <ptrtype>
5555 <struct>jvmtiObjectReferenceCallback</struct>
5556 </ptrtype>
5557 <description>
5558 The callback to be called to describe each
5559 object reference.
5560 </description>
5561 </param>
5562 <param id="user_data">
5563 <inbuf>
5564 <void/>
5565 <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5566 </inbuf>
5567 <description>
5568 User supplied data to be passed to the callback.
5569 </description>
5570 </param>
5571 </parameters>
5572 <errors>
5573 </errors>
5574 </function>
5575
5576 <function id="IterateOverReachableObjects" num="110">
5577 <synopsis>Iterate Over Reachable Objects</synopsis>
5578 <description>
5579 This function iterates over the root objects and all objects that
5580 are directly and indirectly reachable from the root objects.
5581 The root objects comprise the set of system classes,
5582 JNI globals, references from thread stacks, and other objects used as roots
5583 for the purposes of garbage collection.
5584 <p/>
5585 For each root the <paramlink id="heap_root_callback"></paramlink>
5586 or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5587 An object can be a root object for more than one reason and in that case
5588 the appropriate callback is called for each reason.
5589 <p/>
5590 For each object reference the <paramlink id="object_ref_callback"></paramlink>
5591 callback function is called to describe the object reference.
5592 The callback is called exactly once for each reference from a referrer;
5593 this is true even if there are reference cycles or multiple paths to
5594 the referrer.
5595 There may be more than one reference between a referrer and a referree,
5596 These may be distinguished by the
5597 <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5598 <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5599 The callback for an object will always occur after the callback for
5600 its referrer.
5601 <p/>
5602 See <functionlink id="FollowReferences"/> for the object
5603 references which are reported.
5604 <p/>
5605 Roots are always reported to the profiler before any object references
5606 are reported. In other words, the <paramlink id="object_ref_callback"></paramlink>
5607 callback will not be called until the appropriate callback has been called
5608 for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is
5609 specified as <code>NULL</code> then this function returns after
5610 reporting the root objects to the profiler.
5611 <p/>
5612 During the execution of this function the state of the heap
5613 does not change: no objects are allocated, no objects are
5614 garbage collected, and the state of objects (including
5615 held values) does not change.
5616 As a result, threads executing Java
5617 programming language code, threads attempting to resume the
5618 execution of Java programming language code, and threads
5619 attempting to execute JNI functions are typically stalled.
5620 </description>
5621 <origin>new</origin>
5622 <capabilities>
5623 <required id="can_tag_objects"></required>
5624 </capabilities>
5625 <parameters>
5626 <param id="heap_root_callback">
5627 <ptrtype>
5628 <struct>jvmtiHeapRootCallback</struct>
5629 <nullok>do not report heap roots</nullok>
5630 </ptrtype>
5631 <description>
5632 The callback function to be called for each heap root of type
5633 <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5634 <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5635 <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5636 <code>JVMTI_HEAP_ROOT_THREAD</code>, or
5637 <code>JVMTI_HEAP_ROOT_OTHER</code>.
5638 </description>
5639 </param>
5640 <param id="stack_ref_callback">
5641 <ptrtype>
5642 <struct>jvmtiStackReferenceCallback</struct>
5643 <nullok>do not report stack references</nullok>
5644 </ptrtype>
5645 <description>
5646 The callback function to be called for each heap root of
5647 <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5648 <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5649 </description>
5650 </param>
5651 <param id="object_ref_callback">
5652 <ptrtype>
5653 <struct>jvmtiObjectReferenceCallback</struct>
5654 <nullok>do not follow references from the root objects</nullok>
5655 </ptrtype>
5656 <description>
5657 The callback function to be called for each object reference.
5658 </description>
5659 </param>
5660 <param id="user_data">
5661 <inbuf>
5662 <void/>
5663 <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5664 </inbuf>
5665 <description>
5666 User supplied data to be passed to the callback.
5667 </description>
5668 </param>
5669 </parameters>
5670 <errors>
5671 </errors>
5672 </function>
5673
5674 <function id="IterateOverHeap" num="111">
5675 <synopsis>Iterate Over Heap</synopsis>
5676 <description>
5677 Iterate over all objects in the heap. This includes both reachable and
5678 unreachable objects.
5679 <p/>
5680 The <paramlink id="object_filter"></paramlink> parameter indicates the
5681 objects for which the callback function is called. If this parameter
5682 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
5683 called for every object that is tagged. If the parameter is
5684 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5685 for objects that are not tagged. If the parameter
5686 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5687 called for every object in the heap, irrespective of whether it is
5688 tagged or not.
5689 <p/>
5690 During the execution of this function the state of the heap
5691 does not change: no objects are allocated, no objects are
5692 garbage collected, and the state of objects (including
5693 held values) does not change.
5694 As a result, threads executing Java
5695 programming language code, threads attempting to resume the
5696 execution of Java programming language code, and threads
5697 attempting to execute JNI functions are typically stalled.
5698 </description>
5699 <origin>new</origin>
5700 <capabilities>
5701 <required id="can_tag_objects"></required>
5702 </capabilities>
5703 <parameters>
5704 <param id="object_filter">
5705 <enum>jvmtiHeapObjectFilter</enum>
5706 <description>
5707 Indicates the objects for which the callback function is called.
5708 </description>
5709 </param>
5710 <param id="heap_object_callback">
5711 <ptrtype>
5712 <struct>jvmtiHeapObjectCallback</struct>
5713 </ptrtype>
5714 <description>
5715 The iterator function to be called for each
5716 object matching the <paramlink id="object_filter"/>.
5717 </description>
5718 </param>
5719 <param id="user_data">
5720 <inbuf>
5721 <void/>
5722 <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5723 </inbuf>
5724 <description>
5725 User supplied data to be passed to the callback.
5726 </description>
5727 </param>
5728 </parameters>
5729 <errors>
5730 </errors>
5731 </function>
5732
5733 <function id="IterateOverInstancesOfClass" num="112">
5734 <synopsis>Iterate Over Instances Of Class</synopsis>
5735 <description>
5736 Iterate over all objects in the heap that are instances of the specified class.
5737 This includes direct instances of the specified class and
5738 instances of all subclasses of the specified class.
5739 This includes both reachable and unreachable objects.
5740 <p/>
5741 The <paramlink id="object_filter"></paramlink> parameter indicates the
5742 objects for which the callback function is called. If this parameter
5743 is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
5744 called for every object that is tagged. If the parameter is
5745 <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5746 called for objects that are not tagged. If the parameter
5747 is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5748 called for every object in the heap, irrespective of whether it is
5749 tagged or not.
5750 <p/>
5751 During the execution of this function the state of the heap
5752 does not change: no objects are allocated, no objects are
5753 garbage collected, and the state of objects (including
5754 held values) does not change.
5755 As a result, threads executing Java
5756 programming language code, threads attempting to resume the
5757 execution of Java programming language code, and threads
5758 attempting to execute JNI functions are typically stalled.
5759 </description>
5760 <origin>new</origin>
5761 <capabilities>
5762 <required id="can_tag_objects"></required>
5763 </capabilities>
5764 <parameters>
5765 <param id="klass">
5766 <jclass/>
5767 <description>
5768 Iterate over objects of this class only.
5769 </description>
5770 </param>
5771 <param id="object_filter">
5772 <enum>jvmtiHeapObjectFilter</enum>
5773 <description>
5774 Indicates the objects for which the callback function is called.
5775 </description>
5776 </param>
5777 <param id="heap_object_callback">
5778 <ptrtype>
5779 <struct>jvmtiHeapObjectCallback</struct>
5780 </ptrtype>
5781 <description>
5782 The iterator function to be called for each
5783 <paramlink id="klass"/> instance matching
5784 the <paramlink id="object_filter"/>.
5785 </description>
5786 </param>
5787 <param id="user_data">
5788 <inbuf>
5789 <void/>
5790 <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5791 </inbuf>
5792 <description>
5793 User supplied data to be passed to the callback.
5794 </description>
5795 </param>
5796 </parameters>
5797 <errors>
5798 </errors>
5799 </function>
5800
5801 </category>
5802
5803 <category id="local" label="Local Variable">
5804
5805 <intro>
5806 These functions are used to retrieve or set the value of a local variable.
5807 The variable is identified by the depth of the frame containing its
5808 value and the variable's slot number within that frame.
5809 The mapping of variables to
5810 slot numbers can be obtained with the function
5811 <functionlink id="GetLocalVariableTable"></functionlink>.
5812 <p/>
5813 The <code>GetLocalXXX</code> functions may be used to retrieve the value of
5814 a local variable contained in the frame of a virtual thread.
5815 The <code>SetLocalXXX</code> functions may be used to set the value of a
5816 local variable in the topmost frame of a virtual thread suspended at a
5817 breakpoint or single step event. An implementation may support setting locals
5818 in other cases.
5819 </intro>
5820
5821 <function id="GetLocalObject" num="21">
5822 <synopsis>Get Local Variable - Object</synopsis>
5823 <description>
5824 This function can be used to retrieve the value of a local
5825 variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5826 <p/>
5827 The specified thread must be suspended or must be the current thread.
5828 </description>
5829 <origin>jvmdi</origin>
5830 <capabilities>
5831 <required id="can_access_local_variables"></required>
5832 </capabilities>
5833 <parameters>
5834 <param id="thread">
5835 <jthread null="current" frame="frame" impl="noconvert"/>
5836 <description>
5837 The thread of the frame containing the variable's value.
5838 </description>
5839 </param>
5840 <param id="depth">
5841 <jframeID thread="thread"/>
5842 <description>
5843 The depth of the frame containing the variable's value.
5844 </description>
5845 </param>
5846 <param id="slot">
5847 <jint/>
5848 <description>
5849 The variable's slot number.
5850 </description>
5851 </param>
5852 <param id="value_ptr">
5853 <outptr><jobject/></outptr>
5854 <description>
5855 On return, points to the variable's value.
5856 </description>
5857 </param>
5858 </parameters>
5859 <errors>
5860 <error id="JVMTI_ERROR_INVALID_SLOT">
5861 Invalid <code>slot</code>.
5862 </error>
5863 <error id="JVMTI_ERROR_TYPE_MISMATCH">
5864 The variable type is not
5865 <code>Object</code> or a subclass of <code>Object</code>.
5866 </error>
5867 <error id="JVMTI_ERROR_OPAQUE_FRAME">
5868 Not a visible frame
5869 </error>
5870 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5871 Thread was not suspended and was not the current thread.
5872 </error>
5873 </errors>
5874 </function>
5875
5876 <function id="GetLocalInstance" num="155" since="1.2">
5877 <synopsis>Get Local Instance</synopsis>
5878 <description>
5879 This function can be used to retrieve the value of the local object
5880 variable at slot 0 (the "<code>this</code>" object) from non-static
5881 frames. This function can retrieve the "<code>this</code>" object from
5882 native method frames, whereas <code>GetLocalObject()</code> would
5883 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5884 <p/>
5885 The specified thread must be suspended or must be the current thread.
5886 </description>
5887 <origin>new</origin>
5888 <capabilities>
5889 <required id="can_access_local_variables"></required>
5890 </capabilities>
5891 <parameters>
5892 <param id="thread">
5893 <jthread null="current" frame="frame" impl="noconvert"/>
5894 <description>
5895 The thread of the frame containing the variable's value.
5896 </description>
5897 </param>
5898 <param id="depth">
5899 <jframeID thread="thread"/>
5900 <description>
5901 The depth of the frame containing the variable's value.
5902 </description>
5903 </param>
5904 <param id="value_ptr">
5905 <outptr><jobject/></outptr>
5906 <description>
5907 On return, points to the variable's value.
5908 </description>
5909 </param>
5910 </parameters>
5911 <errors>
5912 <error id="JVMTI_ERROR_INVALID_SLOT">
5913 If the specified frame is a static method frame.
5914 </error>
5915 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5916 Thread was not suspended and was not the current thread.
5917 </error>
5918 </errors>
5919 </function>
5920 <function id="GetLocalInt" num="22">
5921 <synopsis>Get Local Variable - Int</synopsis>
5922 <description>
5923 This function can be used to retrieve the value of a local
5924 variable whose type is <code>int</code>,
5925 <code>short</code>, <code>char</code>, <code>byte</code>, or
5926 <code>boolean</code>.
5927 <p/>
5928 The specified thread must be suspended or must be the current thread.
5929 </description>
5930 <origin>jvmdi</origin>
5931 <capabilities>
5932 <required id="can_access_local_variables"></required>
5933 </capabilities>
5934 <parameters>
5935 <param id="thread">
5936 <jthread null="current" frame="frame" impl="noconvert"/>
5937 <description>
5938 The thread of the frame containing the variable's value.
5939 </description>
5940 </param>
5941 <param id="depth">
5942 <jframeID thread="thread"/>
5943 <description>
5944 The depth of the frame containing the variable's value.
5945 </description>
5946 </param>
5947 <param id="slot">
5948 <jint/>
5949 <description>
5950 The variable's slot number.
5951 </description>
5952 </param>
5953 <param id="value_ptr">
5954 <outptr><jint/></outptr>
5955 <description>
5956 On return, points to the variable's value.
5957 </description>
5958 </param>
5959 </parameters>
5960 <errors>
5961 <error id="JVMTI_ERROR_INVALID_SLOT">
5962 Invalid <code>slot</code>.
5963 </error>
5964 <error id="JVMTI_ERROR_TYPE_MISMATCH">
5965 The variable type is not
5966 <code>int</code>, <code>short</code>,
5967 <code>char</code>, <code>byte</code>, or
5968 <code>boolean</code>.
5969 </error>
5970 <error id="JVMTI_ERROR_OPAQUE_FRAME">
5971 Not a visible frame
5972 </error>
5973 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5974 Thread was not suspended and was not the current thread.
5975 </error>
5976 </errors>
5977 </function>
5978
5979 <function id="GetLocalLong" num="23">
5980 <synopsis>Get Local Variable - Long</synopsis>
5981 <description>
5982 This function can be used to retrieve the value of a local
5983 variable whose type is <code>long</code>.
5984 <p/>
5985 The specified thread must be suspended or must be the current thread.
5986 </description>
5987 <origin>jvmdi</origin>
5988 <capabilities>
5989 <required id="can_access_local_variables"></required>
5990 </capabilities>
5991 <parameters>
5992 <param id="thread">
5993 <jthread null="current" frame="frame" impl="noconvert"/>
5994 <description>
5995 The thread of the frame containing the variable's value.
5996 </description>
5997 </param>
5998 <param id="depth">
5999 <jframeID thread="thread"/>
6000 <description>
6001 The depth of the frame containing the variable's value.
6002 </description>
6003 </param>
6004 <param id="slot">
6005 <jint/>
6006 <description>
6007 The variable's slot number.
6008 </description>
6009 </param>
6010 <param id="value_ptr">
6011 <outptr><jlong/></outptr>
6012 <description>
6013 On return, points to the variable's value.
6014 </description>
6015 </param>
6016 </parameters>
6017 <errors>
6018 <error id="JVMTI_ERROR_INVALID_SLOT">
6019 Invalid <code>slot</code>.
6020 </error>
6021 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6022 The variable type is not <code>long</code>.
6023 </error>
6024 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6025 Not a visible frame
6026 </error>
6027 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6028 Thread was not suspended and was not the current thread.
6029 </error>
6030 </errors>
6031 </function>
6032
6033 <function id="GetLocalFloat" num="24">
6034 <synopsis>Get Local Variable - Float</synopsis>
6035 <description>
6036 This function can be used to retrieve the value of a local
6037 variable whose type is <code>float</code>.
6038 <p/>
6039 The specified thread must be suspended or must be the current thread.
6040 </description>
6041 <origin>jvmdi</origin>
6042 <capabilities>
6043 <required id="can_access_local_variables"></required>
6044 </capabilities>
6045 <parameters>
6046 <param id="thread">
6047 <jthread null="current" frame="frame" impl="noconvert"/>
6048 <description>
6049 The thread of the frame containing the variable's value.
6050 </description>
6051 </param>
6052 <param id="depth">
6053 <jframeID thread="thread"/>
6054 <description>
6055 The depth of the frame containing the variable's value.
6056 </description>
6057 </param>
6058 <param id="slot">
6059 <jint/>
6060 <description>
6061 The variable's slot number.
6062 </description>
6063 </param>
6064 <param id="value_ptr">
6065 <outptr><jfloat/></outptr>
6066 <description>
6067 On return, points to the variable's value.
6068 </description>
6069 </param>
6070 </parameters>
6071 <errors>
6072 <error id="JVMTI_ERROR_INVALID_SLOT">
6073 Invalid <code>slot</code>.
6074 </error>
6075 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6076 The variable type is not <code>float</code>.
6077 </error>
6078 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6079 Not a visible frame
6080 </error>
6081 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6082 Thread was not suspended and was not the current thread.
6083 </error>
6084 </errors>
6085 </function>
6086
6087 <function id="GetLocalDouble" num="25">
6088 <synopsis>Get Local Variable - Double</synopsis>
6089 <description>
6090 This function can be used to retrieve the value of a local
6091 variable whose type is <code>long</code>.
6092 <p/>
6093 The specified thread must be suspended or must be the current thread.
6094 </description>
6095 <origin>jvmdi</origin>
6096 <capabilities>
6097 <required id="can_access_local_variables"></required>
6098 </capabilities>
6099 <parameters>
6100 <param id="thread">
6101 <jthread null="current" frame="frame" impl="noconvert"/>
6102 <description>
6103 The thread of the frame containing the variable's value.
6104 </description>
6105 </param>
6106 <param id="depth">
6107 <jframeID thread="thread"/>
6108 <description>
6109 The depth of the frame containing the variable's value.
6110 </description>
6111 </param>
6112 <param id="slot">
6113 <jint/>
6114 <description>
6115 The variable's slot number.
6116 </description>
6117 </param>
6118 <param id="value_ptr">
6119 <outptr><jdouble/></outptr>
6120 <description>
6121 On return, points to the variable's value.
6122 </description>
6123 </param>
6124 </parameters>
6125 <errors>
6126 <error id="JVMTI_ERROR_INVALID_SLOT">
6127 Invalid <code>slot</code>.
6128 </error>
6129 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6130 The variable type is not <code>double</code>.
6131 </error>
6132 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6133 Not a visible frame
6134 </error>
6135 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6136 Thread was not suspended and was not the current thread.
6137 </error>
6138 </errors>
6139 </function>
6140
6141 <function id="SetLocalObject" num="26">
6142 <synopsis>Set Local Variable - Object</synopsis>
6143 <description>
6144 This function can be used to set the value of a local
6145 variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
6146 <p/>
6147 The specified thread must be suspended or must be the current thread.
6148 </description>
6149 <origin>jvmdi</origin>
6150 <capabilities>
6151 <required id="can_access_local_variables"></required>
6152 </capabilities>
6153 <parameters>
6154 <param id="thread">
6155 <jthread null="current" frame="frame" impl="noconvert"/>
6156 <description>
6157 The thread of the frame containing the variable's value.
6158 </description>
6159 </param>
6160 <param id="depth">
6161 <jframeID thread="thread"/>
6162 <description>
6163 The depth of the frame containing the variable's value.
6164 </description>
6165 </param>
6166 <param id="slot">
6167 <jint/>
6168 <description>
6169 The variable's slot number.
6170 </description>
6171 </param>
6172 <param id="value">
6173 <jobject/>
6174 <description>
6175 The new value for the variable.
6176 </description>
6177 </param>
6178 </parameters>
6179 <errors>
6180 <error id="JVMTI_ERROR_INVALID_SLOT">
6181 Invalid <code>slot</code>.
6182 </error>
6183 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6184 The variable type is not
6185 <code>Object</code> or a subclass of <code>Object</code>.
6186 </error>
6187 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6188 The supplied <paramlink id="value"/> is not compatible
6189 with the variable type.
6190 </error>
6191 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6192 Not a visible frame
6193 </error>
6194 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6195 The thread is a virtual thread and the implementation does not support
6196 setting the value of locals in the frame of the given depth.
6197 See <internallink id="local">Local Variables</internallink>.
6198 </error>
6199 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6200 Thread was not suspended and was not the current thread.
6201 </error>
6202 </errors>
6203 </function>
6204
6205 <function id="SetLocalInt" num="27">
6206 <synopsis>Set Local Variable - Int</synopsis>
6207 <description>
6208 This function can be used to set the value of a local
6209 variable whose type is <code>int</code>,
6210 <code>short</code>, <code>char</code>, <code>byte</code>, or
6211 <code>boolean</code>.
6212 <p/>
6213 The specified thread must be suspended or must be the current thread.
6214 </description>
6215 <origin>jvmdi</origin>
6216 <capabilities>
6217 <required id="can_access_local_variables"></required>
6218 </capabilities>
6219 <parameters>
6220 <param id="thread">
6221 <jthread null="current" frame="frame" impl="noconvert"/>
6222 <description>
6223 The thread of the frame containing the variable's value.
6224 </description>
6225 </param>
6226 <param id="depth">
6227 <jframeID thread="thread"/>
6228 <description>
6229 The depth of the frame containing the variable's value.
6230 </description>
6231 </param>
6232 <param id="slot">
6233 <jint/>
6234 <description>
6235 The variable's slot number.
6236 </description>
6237 </param>
6238 <param id="value">
6239 <jint/>
6240 <description>
6241 The new value for the variable.
6242 </description>
6243 </param>
6244 </parameters>
6245 <errors>
6246 <error id="JVMTI_ERROR_INVALID_SLOT">
6247 Invalid <code>slot</code>.
6248 </error>
6249 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6250 The variable type is not
6251 <code>int</code>, <code>short</code>,
6252 <code>char</code>, <code>byte</code>, or
6253 <code>boolean</code>.
6254 </error>
6255 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6256 Not a visible frame
6257 </error>
6258 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6259 The thread is a virtual thread and the implementation does not support
6260 setting the value of locals in the frame of the given depth.
6261 See <internallink id="local">Local Variables</internallink>.
6262 </error>
6263 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6264 Thread was not suspended and was not the current thread.
6265 </error>
6266 </errors>
6267 </function>
6268
6269 <function id="SetLocalLong" num="28">
6270 <synopsis>Set Local Variable - Long</synopsis>
6271 <description>
6272 This function can be used to set the value of a local
6273 variable whose type is <code>long</code>.
6274 <p/>
6275 The specified thread must be suspended or must be the current thread.
6276 </description>
6277 <origin>jvmdi</origin>
6278 <capabilities>
6279 <required id="can_access_local_variables"></required>
6280 </capabilities>
6281 <parameters>
6282 <param id="thread">
6283 <jthread null="current" frame="frame" impl="noconvert"/>
6284 <description>
6285 The thread of the frame containing the variable's value.
6286 </description>
6287 </param>
6288 <param id="depth">
6289 <jframeID thread="thread"/>
6290 <description>
6291 The depth of the frame containing the variable's value.
6292 </description>
6293 </param>
6294 <param id="slot">
6295 <jint/>
6296 <description>
6297 The variable's slot number.
6298 </description>
6299 </param>
6300 <param id="value">
6301 <jlong/>
6302 <description>
6303 The new value for the variable.
6304 </description>
6305 </param>
6306 </parameters>
6307 <errors>
6308 <error id="JVMTI_ERROR_INVALID_SLOT">
6309 Invalid <code>slot</code>.
6310 </error>
6311 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6312 The variable type is not <code>long</code>.
6313 </error>
6314 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6315 Not a visible frame
6316 </error>
6317 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6318 The thread is a virtual thread and the implementation does not support
6319 setting the value of locals in the frame of the given depth.
6320 See <internallink id="local">Local Variables</internallink>.
6321 </error>
6322 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6323 Thread was not suspended and was not the current thread.
6324 </error>
6325 </errors>
6326 </function>
6327
6328 <function id="SetLocalFloat" num="29">
6329 <synopsis>Set Local Variable - Float</synopsis>
6330 <description>
6331 This function can be used to set the value of a local
6332 variable whose type is <code>float</code>.
6333 <p/>
6334 The specified thread must be suspended or must be the current thread.
6335 </description>
6336 <origin>jvmdi</origin>
6337 <capabilities>
6338 <required id="can_access_local_variables"></required>
6339 </capabilities>
6340 <parameters>
6341 <param id="thread">
6342 <jthread null="current" frame="frame" impl="noconvert"/>
6343 <description>
6344 The thread of the frame containing the variable's value.
6345 </description>
6346 </param>
6347 <param id="depth">
6348 <jframeID thread="thread"/>
6349 <description>
6350 The depth of the frame containing the variable's value.
6351 </description>
6352 </param>
6353 <param id="slot">
6354 <jint/>
6355 <description>
6356 The variable's slot number.
6357 </description>
6358 </param>
6359 <param id="value">
6360 <jfloat/>
6361 <description>
6362 The new value for the variable.
6363 </description>
6364 </param>
6365 </parameters>
6366 <errors>
6367 <error id="JVMTI_ERROR_INVALID_SLOT">
6368 Invalid <code>slot</code>.
6369 </error>
6370 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6371 The variable type is not <code>float</code>.
6372 </error>
6373 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6374 Not a visible frame
6375 </error>
6376 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6377 The thread is a virtual thread and the implementation does not support
6378 setting the value of locals in the frame of the given depth.
6379 See <internallink id="local">Local Variables</internallink>.
6380 </error>
6381 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6382 Thread was not suspended and was not the current thread.
6383 </error>
6384 </errors>
6385 </function>
6386
6387 <function id="SetLocalDouble" num="30">
6388 <synopsis>Set Local Variable - Double</synopsis>
6389 <description>
6390 This function can be used to set the value of a local
6391 variable whose type is <code>double</code>.
6392 <p/>
6393 The specified thread must be suspended or must be the current thread.
6394 </description>
6395 <origin>jvmdi</origin>
6396 <capabilities>
6397 <required id="can_access_local_variables"></required>
6398 </capabilities>
6399 <parameters>
6400 <param id="thread">
6401 <jthread null="current" frame="frame" impl="noconvert"/>
6402 <description>
6403 The thread of the frame containing the variable's value.
6404 </description>
6405 </param>
6406 <param id="depth">
6407 <jframeID thread="thread"/>
6408 <description>
6409 The depth of the frame containing the variable's value.
6410 </description>
6411 </param>
6412 <param id="slot">
6413 <jint/>
6414 <description>
6415 The variable's slot number.
6416 </description>
6417 </param>
6418 <param id="value">
6419 <jdouble/>
6420 <description>
6421 The new value for the variable.
6422 </description>
6423 </param>
6424 </parameters>
6425 <errors>
6426 <error id="JVMTI_ERROR_INVALID_SLOT">
6427 Invalid <code>slot</code>.
6428 </error>
6429 <error id="JVMTI_ERROR_TYPE_MISMATCH">
6430 The variable type is not <code>double</code>.
6431 </error>
6432 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6433 Not a visible frame
6434 </error>
6435 <error id="JVMTI_ERROR_OPAQUE_FRAME">
6436 The thread is a virtual thread and the implementation does not support
6437 setting the value of locals in the frame of the given depth.
6438 See <internallink id="local">Local Variables</internallink>.
6439 </error>
6440 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6441 Thread was not suspended and was not the current thread.
6442 </error>
6443 </errors>
6444 </function>
6445 </category>
6446
6447 <category id="breakpointCategory" label="Breakpoint">
6448
6449 <intro>
6450 </intro>
6451
6452 <function id="SetBreakpoint" num="38">
6453 <synopsis>Set Breakpoint</synopsis>
6454 <description>
6455 Set a breakpoint at the instruction indicated by
6456 <code>method</code> and <code>location</code>.
6457 An instruction can only have one breakpoint.
6458 <p/>
6459 Whenever the designated instruction is about to be executed, a
6460 <eventlink id="Breakpoint"></eventlink> event is generated.
6461 </description>
6462 <origin>jvmdi</origin>
6463 <capabilities>
6464 <required id="can_generate_breakpoint_events"></required>
6465 </capabilities>
6466 <parameters>
6467 <param id="klass">
6468 <jclass method="method"/>
6469 <description>
6470 The class in which to set the breakpoint
6471 </description>
6472 </param>
6473 <param id="method">
6474 <jmethodID class="klass"/>
6475 <description>
6476 The method in which to set the breakpoint
6477 </description>
6478 </param>
6479 <param id="location">
6480 <jlocation/>
6481 <description>
6482 the index of the instruction at which to set the breakpoint
6483
6484 </description>
6485 </param>
6486 </parameters>
6487 <errors>
6488 <error id="JVMTI_ERROR_DUPLICATE">
6489 The designated bytecode already has a breakpoint.
6490 </error>
6491 </errors>
6492 </function>
6493
6494 <function id="ClearBreakpoint" num="39">
6495 <synopsis>Clear Breakpoint</synopsis>
6496 <description>
6497 Clear the breakpoint at the bytecode indicated by
6498 <code>method</code> and <code>location</code>.
6499 </description>
6500 <origin>jvmdi</origin>
6501 <capabilities>
6502 <required id="can_generate_breakpoint_events"></required>
6503 </capabilities>
6504 <parameters>
6505 <param id="klass">
6506 <jclass method="method"/>
6507 <description>
6508 The class in which to clear the breakpoint
6509 </description>
6510 </param>
6511 <param id="method">
6512 <jmethodID class="klass"/>
6513 <description>
6514 The method in which to clear the breakpoint
6515 </description>
6516 </param>
6517 <param id="location">
6518 <jlocation/>
6519 <description>
6520 the index of the instruction at which to clear the breakpoint
6521 </description>
6522 </param>
6523 </parameters>
6524 <errors>
6525 <error id="JVMTI_ERROR_NOT_FOUND">
6526 There's no breakpoint at the designated bytecode.
6527 </error>
6528 </errors>
6529 </function>
6530
6531 </category>
6532
6533 <category id="fieldWatch" label="Watched Field">
6534
6535 <intro>
6536 </intro>
6537
6538 <function id="SetFieldAccessWatch" num="41">
6539 <synopsis>Set Field Access Watch</synopsis>
6540 <description>
6541 Generate a <eventlink id="FieldAccess"></eventlink> event
6542 when the field specified
6543 by <code>klass</code> and
6544 <code>field</code> is about to be accessed.
6545 An event will be generated for each access of the field
6546 until it is canceled with
6547 <functionlink id="ClearFieldAccessWatch"></functionlink>.
6548 Field accesses from Java programming language code or from JNI code are watched,
6549 fields modified by other means are not watched.
6550 Note that <jvmti/> users should be aware that their own field accesses
6551 will trigger the watch.
6552 A field can only have one field access watch set.
6553 Modification of a field is not considered an access--use
6554 <functionlink id="SetFieldModificationWatch"></functionlink>
6555 to monitor modifications.
6556 </description>
6557 <origin>jvmdi</origin>
6558 <capabilities>
6559 <required id="can_generate_field_access_events"></required>
6560 </capabilities>
6561 <parameters>
6562 <param id="klass">
6563 <jclass field="field"/>
6564 <description>
6565 The class containing the field to watch
6566 </description>
6567 </param>
6568 <param id="field">
6569 <jfieldID class="klass"/>
6570 <description>
6571 The field to watch
6572
6573 </description>
6574 </param>
6575 </parameters>
6576 <errors>
6577 <error id="JVMTI_ERROR_DUPLICATE">
6578 The designated field is already being watched for accesses.
6579 </error>
6580 </errors>
6581 </function>
6582
6583 <function id="ClearFieldAccessWatch" num="42">
6584 <synopsis>Clear Field Access Watch</synopsis>
6585 <description>
6586 Cancel a field access watch previously set by
6587 <functionlink id="SetFieldAccessWatch"></functionlink>, on the
6588 field specified
6589 by <code>klass</code> and
6590 <code>field</code>.
6591 </description>
6592 <origin>jvmdi</origin>
6593 <capabilities>
6594 <required id="can_generate_field_access_events"></required>
6595 </capabilities>
6596 <parameters>
6597 <param id="klass">
6598 <jclass field="field"/>
6599 <description>
6600 The class containing the field to watch
6601 </description>
6602 </param>
6603 <param id="field">
6604 <jfieldID class="klass"/>
6605 <description>
6606 The field to watch
6607
6608 </description>
6609 </param>
6610 </parameters>
6611 <errors>
6612 <error id="JVMTI_ERROR_NOT_FOUND">
6613 The designated field is not being watched for accesses.
6614 </error>
6615 </errors>
6616 </function>
6617
6618 <function id="SetFieldModificationWatch" num="43">
6619 <synopsis>Set Field Modification Watch</synopsis>
6620 <description>
6621 Generate a <eventlink id="FieldModification"></eventlink> event
6622 when the field specified
6623 by <code>klass</code> and
6624 <code>field</code> is about to be modified.
6625 An event will be generated for each modification of the field
6626 until it is canceled with
6627 <functionlink id="ClearFieldModificationWatch"></functionlink>.
6628 Field modifications from Java programming language code or from JNI code are watched,
6629 fields modified by other means are not watched.
6630 Note that <jvmti/> users should be aware that their own field modifications
6631 will trigger the watch.
6632 A field can only have one field modification watch set.
6633 </description>
6634 <origin>jvmdi</origin>
6635 <capabilities>
6636 <required id="can_generate_field_modification_events"></required>
6637 </capabilities>
6638 <parameters>
6639 <param id="klass">
6640 <jclass field="field"/>
6641 <description>
6642 The class containing the field to watch
6643 </description>
6644 </param>
6645 <param id="field">
6646 <jfieldID class="klass"/>
6647 <description>
6648 The field to watch
6649
6650 </description>
6651 </param>
6652 </parameters>
6653 <errors>
6654 <error id="JVMTI_ERROR_DUPLICATE">
6655 The designated field is already being watched for modifications.
6656 </error>
6657 </errors>
6658 </function>
6659
6660 <function id="ClearFieldModificationWatch" num="44">
6661 <synopsis>Clear Field Modification Watch</synopsis>
6662 <description>
6663
6664 Cancel a field modification watch previously set by
6665 <functionlink id="SetFieldModificationWatch"></functionlink>, on the
6666 field specified
6667 by <code>klass</code> and
6668 <code>field</code>.
6669 </description>
6670 <origin>jvmdi</origin>
6671 <capabilities>
6672 <required id="can_generate_field_modification_events"></required>
6673 </capabilities>
6674 <parameters>
6675 <param id="klass">
6676 <jclass field="field"/>
6677 <description>
6678 The class containing the field to watch
6679 </description>
6680 </param>
6681 <param id="field">
6682 <jfieldID class="klass"/>
6683 <description>
6684 The field to watch
6685
6686 </description>
6687 </param>
6688 </parameters>
6689 <errors>
6690 <error id="JVMTI_ERROR_NOT_FOUND">
6691 The designated field is not being watched for modifications.
6692 </error>
6693 </errors>
6694 </function>
6695 </category>
6696
6697 <category id="module" label="Module">
6698
6699 <intro>
6700 </intro>
6701
6702 <function id="GetAllModules" num="3" since="9">
6703 <synopsis>Get All Modules</synopsis>
6704 <description>
6705 Return an array of all modules loaded in the virtual machine.
6706 The array includes the unnamed module for each class loader.
6707 The number of modules in the array is returned via
6708 <code>module_count_ptr</code>, and the array itself via
6709 <code>modules_ptr</code>.
6710 <p/>
6711 </description>
6712 <origin>new</origin>
6713 <capabilities>
6714 </capabilities>
6715 <parameters>
6716 <param id="module_count_ptr">
6717 <outptr><jint/></outptr>
6718 <description>
6719 On return, points to the number of returned modules.
6720 </description>
6721 </param>
6722 <param id="modules_ptr">
6723 <allocbuf outcount="module_count_ptr"><jobject/></allocbuf>
6724 <description>
6725 On return, points to an array of references, one
6726 for each module.
6727 </description>
6728 </param>
6729 </parameters>
6730 <errors>
6731 </errors>
6732 </function>
6733
6734 <function id="GetNamedModule" num="40" since="9">
6735 <synopsis>Get Named Module</synopsis>
6736 <description>
6737 Return the <code>java.lang.Module</code> object for a named
6738 module defined to a class loader that contains a given package.
6739 The module is returned via <code>module_ptr</code>.
6740 <p/>
6741 If a named module is defined to the class loader and it
6742 contains the package then that named module is returned,
6743 otherwise <code>NULL</code> is returned.
6744 <p/>
6745 </description>
6746 <origin>new</origin>
6747 <capabilities>
6748 </capabilities>
6749 <parameters>
6750 <param id="class_loader">
6751 <ptrtype>
6752 <jobject/>
6753 <nullok>the bootstrap loader is assumed</nullok>
6754 </ptrtype>
6755 <description>
6756 A class loader.
6757 If the <code>class_loader</code> is not <code>NULL</code>
6758 or a subclass of <code>java.lang.ClassLoader</code>
6759 this function returns
6760 <errorlink id="JVMTI_ERROR_ILLEGAL_ARGUMENT"></errorlink>.
6761 </description>
6762 </param>
6763 <param id="package_name">
6764 <inbuf><char/></inbuf>
6765 <description>
6766 The name of the package, encoded as a
6767 <internallink id="mUTF">modified UTF-8</internallink> string.
6768 The package name is in internal form (JVMS 4.2.1);
6769 identifiers are separated by forward slashes rather than periods.
6770 </description>
6771 </param>
6772 <param id="module_ptr">
6773 <outptr><jobject/></outptr>
6774 <description>
6775 On return, points to a <code>java.lang.Module</code> object
6776 or points to <code>NULL</code>.
6777 </description>
6778 </param>
6779 </parameters>
6780 <errors>
6781 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6782 If class loader is not <code>NULL</code> and is not a class loader object.
6783 </error>
6784 </errors>
6785 </function>
6786
6787 <function id="AddModuleReads" num="94" since="9">
6788 <synopsis>Add Module Reads</synopsis>
6789 <description>
6790 Update a module to read another module. This function is a no-op
6791 when <paramlink id="module"></paramlink> is an unnamed module.
6792 This function facilitates the instrumentation of code
6793 in named modules where that instrumentation requires
6794 expanding the set of modules that a module reads.
6795 </description>
6796 <origin>new</origin>
6797 <capabilities>
6798 </capabilities>
6799 <parameters>
6800 <param id="module">
6801 <ptrtype><jobject/></ptrtype>
6802 <description>
6803 The module to update.
6804 </description>
6805 </param>
6806 <param id="to_module">
6807 <ptrtype><jobject/></ptrtype>
6808 <description>
6809 The additional module to read.
6810 </description>
6811 </param>
6812 </parameters>
6813 <errors>
6814 <error id="JVMTI_ERROR_INVALID_MODULE">
6815 If <paramlink id="module"></paramlink> is not a module object.
6816 </error>
6817 <error id="JVMTI_ERROR_INVALID_MODULE">
6818 If <paramlink id="to_module"></paramlink> is not a module object.
6819 </error>
6820 <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6821 if the module cannot be modified.
6822 See <functionlink id="IsModifiableModule"/>.
6823 </error>
6824 </errors>
6825 </function>
6826
6827 <function id="AddModuleExports" num="95" since="9">
6828 <synopsis>Add Module Exports</synopsis>
6829 <description>
6830 Update a module to export a package to another module.
6831 This function is a no-op when <paramlink id="module"></paramlink>
6832 is an unnamed module or an open module.
6833 This function facilitates the instrumentation of code
6834 in named modules where that instrumentation requires
6835 expanding the set of packages that a module exports.
6836 </description>
6837 <origin>new</origin>
6838 <capabilities>
6839 </capabilities>
6840 <parameters>
6841 <param id="module">
6842 <ptrtype><jobject/></ptrtype>
6843 <description>
6844 The module to update.
6845 </description>
6846 </param>
6847 <param id="pkg_name">
6848 <inbuf><char/></inbuf>
6849 <description>
6850 The exported package name.
6851 </description>
6852 </param>
6853 <param id="to_module">
6854 <ptrtype><jobject/></ptrtype>
6855 <description>
6856 The module the package is exported to.
6857 If the <code>to_module</code> is not a subclass of
6858 <code>java.lang.Module</code> this function returns
6859 <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6860 </description>
6861 </param>
6862 </parameters>
6863 <errors>
6864 <error id="JVMTI_ERROR_INVALID_MODULE">
6865 If <paramlink id="module"></paramlink> is not a module object.
6866 </error>
6867 <error id="JVMTI_ERROR_INVALID_MODULE">
6868 If <paramlink id="to_module"></paramlink> is not a module object.
6869 </error>
6870 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6871 If the package <paramlink id="pkg_name"></paramlink>
6872 does not belong to the module.
6873 </error>
6874 <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6875 if the module cannot be modified.
6876 See <functionlink id="IsModifiableModule"/>.
6877 </error>
6878 </errors>
6879 </function>
6880
6881 <function id="AddModuleOpens" num="96" since="9">
6882 <synopsis>Add Module Opens</synopsis>
6883 <description>
6884 Update a module to open a package to another module.
6885 This function is a no-op when <paramlink id="module"></paramlink>
6886 is an unnamed module or an open module.
6887 This function facilitates the instrumentation of code
6888 in modules where that instrumentation requires
6889 expanding the set of packages that a module opens to
6890 other modules.
6891 </description>
6892 <origin>new</origin>
6893 <capabilities>
6894 </capabilities>
6895 <parameters>
6896 <param id="module">
6897 <ptrtype><jobject/></ptrtype>
6898 <description>
6899 The module to update.
6900 </description>
6901 </param>
6902 <param id="pkg_name">
6903 <inbuf><char/></inbuf>
6904 <description>
6905 The package name of the package to open.
6906 </description>
6907 </param>
6908 <param id="to_module">
6909 <ptrtype><jobject/></ptrtype>
6910 <description>
6911 The module with the package to open.
6912 If the <code>to_module</code> is not a subclass of
6913 <code>java.lang.Module</code> this function returns
6914 <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6915 </description>
6916 </param>
6917 </parameters>
6918 <errors>
6919 <error id="JVMTI_ERROR_INVALID_MODULE">
6920 If <paramlink id="module"></paramlink> is not a module object.
6921 </error>
6922 <error id="JVMTI_ERROR_INVALID_MODULE">
6923 If <paramlink id="to_module"></paramlink> is not a module object.
6924 </error>
6925 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6926 If the package <paramlink id="pkg_name"></paramlink>
6927 does not belong to the module.
6928 </error>
6929 <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6930 if the module cannot be modified.
6931 See <functionlink id="IsModifiableModule"/>.
6932 </error>
6933 </errors>
6934 </function>
6935
6936 <function id="AddModuleUses" num="97" since="9">
6937 <synopsis>Add Module Uses</synopsis>
6938 <description>
6939 Updates a module to add a service to the set of services that
6940 a module uses. This function is a no-op when the module
6941 is an unnamed module.
6942 This function facilitates the instrumentation of code
6943 in named modules where that instrumentation requires
6944 expanding the set of services that a module is using.
6945 </description>
6946 <origin>new</origin>
6947 <capabilities>
6948 </capabilities>
6949 <parameters>
6950 <param id="module">
6951 <ptrtype><jobject/></ptrtype>
6952 <description>
6953 The module to update.
6954 </description>
6955 </param>
6956 <param id="service">
6957 <ptrtype><jclass/></ptrtype>
6958 <description>
6959 The service to use.
6960 </description>
6961 </param>
6962 </parameters>
6963 <errors>
6964 <error id="JVMTI_ERROR_INVALID_MODULE">
6965 If <paramlink id="module"></paramlink> is not a module object.
6966 </error>
6967 <error id="JVMTI_ERROR_INVALID_CLASS">
6968 If <paramlink id="service"></paramlink> is not a class object.
6969 </error>
6970 <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6971 if the module cannot be modified.
6972 See <functionlink id="IsModifiableModule"/>.
6973 </error>
6974 </errors>
6975 </function>
6976
6977 <function id="AddModuleProvides" num="98" since="9">
6978 <synopsis>Add Module Provides</synopsis>
6979 <description>
6980 Updates a module to add a service to the set of services that
6981 a module provides. This function is a no-op when the module
6982 is an unnamed module.
6983 This function facilitates the instrumentation of code
6984 in named modules where that instrumentation requires
6985 changes to the services that are provided.
6986 </description>
6987 <origin>new</origin>
6988 <capabilities>
6989 </capabilities>
6990 <parameters>
6991 <param id="module">
6992 <ptrtype><jobject/></ptrtype>
6993 <description>
6994 The module to update.
6995 </description>
6996 </param>
6997 <param id="service">
6998 <ptrtype><jclass/></ptrtype>
6999 <description>
7000 The service to provide.
7001 </description>
7002 </param>
7003 <param id="impl_class">
7004 <ptrtype><jclass/></ptrtype>
7005 <description>
7006 The implementation class for the provided service.
7007 </description>
7008 </param>
7009 </parameters>
7010 <errors>
7011 <error id="JVMTI_ERROR_INVALID_MODULE">
7012 If <paramlink id="module"></paramlink> is not a module object.
7013 </error>
7014 <error id="JVMTI_ERROR_INVALID_CLASS">
7015 If <paramlink id="service"></paramlink> is not a class object.
7016 </error>
7017 <error id="JVMTI_ERROR_INVALID_CLASS">
7018 If <paramlink id="impl_class"></paramlink> is not a class object.
7019 </error>
7020 <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
7021 if the module cannot be modified.
7022 See <functionlink id="IsModifiableModule"/>.
7023 </error>
7024 </errors>
7025 </function>
7026
7027 <function id="IsModifiableModule" num="99" since="9">
7028 <synopsis>Is Modifiable Module</synopsis>
7029 <description>
7030 Determines whether a module is modifiable.
7031 If a module is modifiable then this module can be updated with
7032 <functionlink id="AddModuleReads"/>, <functionlink id="AddModuleExports"/>,
7033 <functionlink id="AddModuleOpens"/>, <functionlink id="AddModuleUses"/>,
7034 and <functionlink id="AddModuleProvides"/>. If a module is not modifiable
7035 then the module can not be updated with these functions. The result of
7036 this function is always <code>JNI_TRUE</code> when called to determine
7037 if an unnamed module is modifiable.
7038 </description>
7039 <origin>new</origin>
7040 <capabilities>
7041 </capabilities>
7042 <parameters>
7043 <param id="module">
7044 <ptrtype><jobject/></ptrtype>
7045 <description>
7046 The module to query.
7047 </description>
7048 </param>
7049 <param id="is_modifiable_module_ptr">
7050 <outptr><jboolean/></outptr>
7051 <description>
7052 On return, points to the boolean result of this function.
7053 </description>
7054 </param>
7055 </parameters>
7056 <errors>
7057 <error id="JVMTI_ERROR_INVALID_MODULE">
7058 If <paramlink id="module"></paramlink> is not a module object.
7059 </error>
7060 </errors>
7061 </function>
7062
7063 </category>
7064
7065 <category id="class" label="Class">
7066 <function id="GetLoadedClasses" jkernel="yes" num="78">
7067 <synopsis>Get Loaded Classes</synopsis>
7068 <description>
7069 Return an array of all classes loaded in the virtual machine.
7070 The number of classes in the array is returned via
7071 <code>class_count_ptr</code>, and the array itself via
7072 <code>classes_ptr</code>.
7073 <p/>
7074 A class or interface creation can be triggered by one of the following:
7075 <ul>
7076 <li>By loading and deriving a class from a <code>class</code> file representation
7077 using a class loader (see <vmspec chapter="5.3"/>).</li>
7078 <li>By invoking <externallink id="../api/java.base/java/lang/invoke/MethodHandles.Lookup.html#defineHiddenClass(byte%5B%5D,boolean,java.lang.invoke.MethodHandles.Lookup.ClassOption...)">Lookup::defineHiddenClass</externallink>
7079 that creates a hidden class or interface from a <code>class</code> file representation.</li>
7080 <li>By invoking methods in certain Java SE Platform APIs such as reflection.</li>
7081 </ul>
7082 <p/>
7083 An array class is created directly by the Java virtual machine. The creation
7084 can be triggered by using class loaders or by invoking methods in certain
7085 Java SE Platform APIs such as reflection.
7086 <p/>
7087 The returned list includes all classes and interfaces, including
7088 <externallink id="../api/java.base/java/lang/Class.html#isHidden()">
7089 hidden classes or interfaces</externallink>,
7090 and also array classes of all types
7091 (including arrays of primitive types).
7092 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) are
7093 <i>not</i> included in the returned list.
7094 </description>
7095 <origin>jvmdi</origin>
7096 <capabilities>
7097 </capabilities>
7098 <parameters>
7099 <param id="class_count_ptr">
7100 <outptr><jint/></outptr>
7101 <description>
7102 On return, points to the number of classes.
7103 </description>
7104 </param>
7105 <param id="classes_ptr">
7106 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
7107 <description>
7108 On return, points to an array of references, one
7109 for each class.
7110 </description>
7111 </param>
7112 </parameters>
7113 <errors>
7114 </errors>
7115 </function>
7116
7117 <function id="GetClassLoaderClasses" jkernel="yes" num="79">
7118 <synopsis>Get Classloader Classes</synopsis>
7119 <description>
7120 Returns an array of all classes which this class loader
7121 can find by name via
7122 <externallink id="../api/java.base/java/lang/ClassLoader.html#loadClass(java.lang.String,boolean)">ClassLoader::loadClass</externallink>,
7123 <externallink id="../api/java.base/java/lang/Class.html#forName(java.lang.String,boolean,java.lang.ClassLoader)">Class::forName</externallink> and bytecode linkage.
7124 That is, all classes for which <code>initiating_loader</code>
7125 has been recorded as an initiating loader.
7126 Each class in the returned array was created by this class loader,
7127 either by defining it directly or by delegation to another class loader.
7128 See <vmspec chapter="5.3"/>.
7129 <p/>
7130 The returned list does not include
7131 <externallink id="../api/java.base/java/lang/Class.html#isHidden()">hidden
7132 classes or interfaces</externallink> or array classes whose
7133 element type is a hidden class or interface as they cannot be discovered
7134 by any class loader.
7135 <p/>
7136 The number of classes in the array is returned via
7137 <code>class_count_ptr</code>, and the array itself via
7138 <code>classes_ptr</code>.
7139 <p/>
7140 See <externallink id="../api/java.base/java/lang/invoke/MethodHandles.Lookup.html#defineHiddenClass(byte%5B%5D,boolean,java.lang.invoke.MethodHandles.Lookup.ClassOption...)">Lookup::defineHiddenClass</externallink>.
7141 </description>
7142 <origin>jvmdi</origin>
7143 <capabilities>
7144 </capabilities>
7145 <parameters>
7146 <param id="initiating_loader">
7147 <ptrtype>
7148 <jobject/>
7149 <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
7150 </ptrtype>
7151 <description>
7152 An initiating class loader.
7153 </description>
7154 </param>
7155 <param id="class_count_ptr">
7156 <outptr><jint/></outptr>
7157 <description>
7158 On return, points to the number of classes.
7159 </description>
7160 </param>
7161 <param id="classes_ptr">
7162 <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
7163 <description>
7164 On return, points to an array of references, one
7165 for each class.
7166 </description>
7167 </param>
7168 </parameters>
7169 <errors>
7170 </errors>
7171 </function>
7172
7173 <function id="GetClassSignature" phase="start" num="48">
7174 <synopsis>Get Class Signature</synopsis>
7175 <description>
7176 Return the name and the generic signature of the class indicated by <code>klass</code>.
7177 <p/>
7178 If the class is a class or interface, then:
7179 <ul>
7180 <li>If the class or interface is not <externallink id="../api/java.base/java/lang/Class.html#isHidden()">hidden</externallink>,
7181 then the returned name is the <externallink id="jni/types.html#type-signatures">
7182 JNI type signature</externallink>.
7183 For example, java.util.List is "Ljava/util/List;"
7184 </li>
7185 <li>If the class or interface is <externallink id="../api/java.base/java/lang/Class.html#isHidden()">hidden</externallink>,
7186 then the returned name is a string of the form:
7187 <code>"L" + N + "." + S + ";"</code>
7188 where <code>N</code> is the binary name encoded in internal form (JVMS 4.2.1)
7189 indicated by the <code>class</code> file passed to
7190 <externallink id="../api/java.base/java/lang/invoke/MethodHandles.Lookup.html#defineHiddenClass(byte%5B%5D,boolean,java.lang.invoke.MethodHandles.Lookup.ClassOption...)">Lookup::defineHiddenClass</externallink>,
7191 and <code>S</code> is an unqualified name.
7192 The returned name is not a type descriptor and does not conform to JVMS 4.3.2.
7193 For example, com.foo.Foo/AnySuffix is "Lcom/foo/Foo.AnySuffix;"
7194 </li>
7195 </ul>
7196 <p/>
7197 If the class indicated by <code>klass</code> represents an array class, then
7198 the returned name is a string consisting of one or more "<code>[</code>" characters
7199 representing the depth of the array nesting, followed by the class signature
7200 of the element type. For example the class signature of java.lang.String[] is
7201 "[Ljava/lang/String;" and that of int[] is "[I".
7202 <p/>
7203 If the class indicated by <code>klass</code> represents primitive type or <code>void</code>,
7204 then the returned name is the <externallink id="jni/types.html#type-signatures">
7205 type signature character of the corresponding primitive type</externallink>.
7206 For example, java.lang.Integer.TYPE is "I".
7207 </description>
7208 <origin>jvmdiClone</origin>
7209 <capabilities>
7210 </capabilities>
7211 <parameters>
7212 <param id="klass">
7213 <jclass/>
7214 <description>
7215 The class to query.
7216 </description>
7217 </param>
7218 <param id="signature_ptr">
7219 <allocbuf>
7220 <char/>
7221 <nullok>the signature is not returned</nullok>
7222 </allocbuf>
7223 <description>
7224 On return, points to the JNI type signature of the class, encoded as a
7225 <internallink id="mUTF">modified UTF-8</internallink> string.
7226 </description>
7227 </param>
7228 <param id="generic_ptr">
7229 <allocbuf>
7230 <char/>
7231 <nullok>the generic signature is not returned</nullok>
7232 </allocbuf>
7233 <description>
7234 On return, points to the generic signature of the class, encoded as a
7235 <internallink id="mUTF">modified UTF-8</internallink> string.
7236 If there is no generic signature attribute for the class, then,
7237 on return, points to <code>NULL</code>.
7238 </description>
7239 </param>
7240 </parameters>
7241 <errors>
7242 </errors>
7243 </function>
7244
7245 <function id="GetClassStatus" phase="start" num="49">
7246 <synopsis>Get Class Status</synopsis>
7247 <description>
7248 Get the status of the class. Zero or more of the following bits can be
7249 set.
7250 <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
7251 <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
7252 Class bytecodes have been verified
7253 </constant>
7254 <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
7255 Class preparation is complete
7256 </constant>
7257 <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
7258 Class initialization is complete. Static initializer has been run.
7259 </constant>
7260 <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
7261 Error during initialization makes class unusable
7262 </constant>
7263 <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
7264 Class is an array. If set, all other bits are zero.
7265 </constant>
7266 <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
7267 Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).
7268 If set, all other bits are zero.
7269 </constant>
7270 </constants>
7271 </description>
7272 <origin>jvmdi</origin>
7273 <capabilities>
7274 </capabilities>
7275 <parameters>
7276 <param id="klass">
7277 <jclass/>
7278 <description>
7279 The class to query.
7280 </description>
7281 </param>
7282 <param id="status_ptr">
7283 <outptr><jint/></outptr>
7284 <description>
7285 On return, points to the current state of this class as one or
7286 more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
7287 </description>
7288 </param>
7289 </parameters>
7290 <errors>
7291 </errors>
7292 </function>
7293
7294 <function id="GetSourceFileName" phase="start" num="50">
7295 <synopsis>Get Source File Name</synopsis>
7296 <description>
7297 For the class indicated by <code>klass</code>, return the source file
7298 name via <code>source_name_ptr</code>. The returned string
7299 is a file name only and never contains a directory name.
7300 <p/>
7301 For primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
7302 and for arrays this function returns
7303 <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
7304 </description>
7305 <origin>jvmdi</origin>
7306 <capabilities>
7307 <required id="can_get_source_file_name"></required>
7308 </capabilities>
7309 <parameters>
7310 <param id="klass">
7311 <jclass/>
7312 <description>
7313 The class to query.
7314 </description>
7315 </param>
7316 <param id="source_name_ptr">
7317 <allocbuf><char/></allocbuf>
7318 <description>
7319 On return, points to the class's source file name, encoded as a
7320 <internallink id="mUTF">modified UTF-8</internallink> string.
7321 </description>
7322 </param>
7323 </parameters>
7324 <errors>
7325 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7326 Class information does not include a source file name. This includes
7327 cases where the class is an array class or primitive class.
7328 </error>
7329 </errors>
7330 </function>
7331
7332 <function id="GetClassModifiers" phase="start" num="51">
7333 <synopsis>Get Class Modifiers</synopsis>
7334 <description>
7335 For the class indicated by <code>klass</code>, return the access
7336 flags
7337 via <code>modifiers_ptr</code>.
7338 Access flags are defined in <vmspec chapter="4"/>.
7339 <p/>
7340 If the class is an array class, then its public, private, and protected
7341 modifiers are the same as those of its component type. For arrays of
7342 primitives, this component type is represented by one of the primitive
7343 classes (for example, <code>java.lang.Integer.TYPE</code>).
7344 <p/>
7345 If the class is a primitive class, its public modifier is always true,
7346 and its protected and private modifiers are always false.
7347 <p/>
7348 If the class is an array class or a primitive class then its final
7349 modifier is always true and its interface modifier is always false.
7350 The values of its other modifiers are not determined by this specification.
7351
7352 </description>
7353 <origin>jvmdi</origin>
7354 <capabilities>
7355 </capabilities>
7356 <parameters>
7357 <param id="klass">
7358 <jclass/>
7359 <description>
7360 The class to query.
7361 </description>
7362 </param>
7363 <param id="modifiers_ptr">
7364 <outptr><jint/></outptr>
7365 <description>
7366 On return, points to the current access flags of this class.
7367
7368 </description>
7369 </param>
7370 </parameters>
7371 <errors>
7372 </errors>
7373 </function>
7374
7375 <function id="GetClassMethods" phase="start" num="52">
7376 <synopsis>Get Class Methods</synopsis>
7377 <description>
7378 For the class indicated by <code>klass</code>, return a count of
7379 methods via <code>method_count_ptr</code> and a list of
7380 method IDs via <code>methods_ptr</code>. The method list contains
7381 constructors and static initializers as well as true methods.
7382 Only directly declared methods are returned (not inherited methods).
7383 An empty method list is returned for array classes and primitive classes
7384 (for example, <code>java.lang.Integer.TYPE</code>).
7385 </description>
7386 <origin>jvmdi</origin>
7387 <capabilities>
7388 <capability id="can_maintain_original_method_order"/>
7389 </capabilities>
7390 <parameters>
7391 <param id="klass">
7392 <jclass/>
7393 <description>
7394 The class to query.
7395 </description>
7396 </param>
7397 <param id="method_count_ptr">
7398 <outptr><jint/></outptr>
7399 <description>
7400 On return, points to the number of methods declared in this class.
7401 </description>
7402 </param>
7403 <param id="methods_ptr">
7404 <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
7405 <description>
7406 On return, points to the method ID array.
7407 </description>
7408 </param>
7409 </parameters>
7410 <errors>
7411 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7412 <paramlink id="klass"></paramlink> is not prepared.
7413 </error>
7414 </errors>
7415 </function>
7416
7417 <function id="GetClassFields" phase="start" num="53">
7418 <synopsis>Get Class Fields</synopsis>
7419 <description>
7420 For the class indicated by <code>klass</code>, return a count of fields
7421 via <code>field_count_ptr</code> and a list of field IDs via
7422 <code>fields_ptr</code>.
7423 Only directly declared fields are returned (not inherited fields).
7424 Fields are returned in the order they occur in the class file.
7425 An empty field list is returned for array classes and primitive classes
7426 (for example, <code>java.lang.Integer.TYPE</code>).
7427 Use JNI to determine the length of an array.
7428 </description>
7429 <origin>jvmdi</origin>
7430 <capabilities>
7431 </capabilities>
7432 <parameters>
7433 <param id="klass">
7434 <jclass/>
7435 <description>
7436 The class to query.
7437 </description>
7438 </param>
7439 <param id="field_count_ptr">
7440 <outptr><jint/></outptr>
7441 <description>
7442 On return, points to the number of fields declared in this class.
7443 </description>
7444 </param>
7445 <param id="fields_ptr">
7446 <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
7447 <description>
7448 On return, points to the field ID array.
7449 </description>
7450 </param>
7451 </parameters>
7452 <errors>
7453 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7454 <paramlink id="klass"></paramlink> is not prepared.
7455 </error>
7456 </errors>
7457 </function>
7458
7459 <function id="GetImplementedInterfaces" phase="start" num="54">
7460 <synopsis>Get Implemented Interfaces</synopsis>
7461 <description>
7462 Return the direct super-interfaces of this class. For a class, this
7463 function returns the interfaces declared in its <code>implements</code>
7464 clause. For an interface, this function returns the interfaces declared in
7465 its <code>extends</code> clause.
7466 An empty interface list is returned for array classes and primitive classes
7467 (for example, <code>java.lang.Integer.TYPE</code>).
7468 </description>
7469 <origin>jvmdi</origin>
7470 <capabilities>
7471 </capabilities>
7472 <parameters>
7473 <param id="klass">
7474 <jclass/>
7475 <description>
7476 The class to query.
7477 </description>
7478 </param>
7479 <param id="interface_count_ptr">
7480 <outptr><jint/></outptr>
7481 <description>
7482 On return, points to the number of interfaces.
7483 </description>
7484 </param>
7485 <param id="interfaces_ptr">
7486 <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
7487 <description>
7488 On return, points to the interface array.
7489 </description>
7490 </param>
7491 </parameters>
7492 <errors>
7493 <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7494 <paramlink id="klass"></paramlink> is not prepared.
7495 </error>
7496 </errors>
7497 </function>
7498
7499 <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
7500 <synopsis>Get Class Version Numbers</synopsis>
7501 <description>
7502 For the class indicated by <code>klass</code>,
7503 return the minor and major version numbers,
7504 as defined in
7505 <vmspec chapter="4"/>.
7506 </description>
7507 <origin>new</origin>
7508 <capabilities>
7509 </capabilities>
7510 <parameters>
7511 <param id="klass">
7512 <jclass/>
7513 <description>
7514 The class to query.
7515 </description>
7516 </param>
7517 <param id="minor_version_ptr">
7518 <outptr><jint/></outptr>
7519 <description>
7520 On return, points to the value of the
7521 <code>minor_version</code> item of the
7522 Class File Format.
7523 Note: to be consistent with the Class File Format,
7524 the minor version number is the first parameter.
7525 </description>
7526 </param>
7527 <param id="major_version_ptr">
7528 <outptr><jint/></outptr>
7529 <description>
7530 On return, points to the value of the
7531 <code>major_version</code> item of the
7532 Class File Format.
7533 </description>
7534 </param>
7535 </parameters>
7536 <errors>
7537 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7538 The class is a primitive or array class.
7539 </error>
7540 </errors>
7541 </function>
7542
7543 <function id="GetConstantPool" phase="start" num="146" since="1.1">
7544 <synopsis>Get Constant Pool</synopsis>
7545 <description>
7546 For the class indicated by <code>klass</code>,
7547 return the raw bytes of the constant pool in the format of the
7548 <code>constant_pool</code> item of
7549 <vmspec chapter="4"/>.
7550 The format of the constant pool may differ between versions
7551 of the Class File Format, so, the
7552 <functionlink id="GetClassVersionNumbers">minor and major
7553 class version numbers</functionlink> should be checked for
7554 compatibility.
7555 <p/>
7556 The returned constant pool might not have the same layout or
7557 contents as the constant pool in the defining class file.
7558 The constant pool returned by GetConstantPool() may have
7559 more or fewer entries than the defining constant pool.
7560 Entries may be in a different order.
7561 The constant pool returned by GetConstantPool() will match the
7562 constant pool used by
7563 <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
7564 That is, the bytecodes returned by GetBytecodes() will have
7565 constant pool indices which refer to constant pool entries returned
7566 by GetConstantPool().
7567 Note that since <functionlink id="RetransformClasses"/>
7568 and <functionlink id="RedefineClasses"/> can change
7569 the constant pool, the constant pool returned by this function
7570 can change accordingly. Thus, the correspondence between
7571 GetConstantPool() and GetBytecodes() does not hold if there
7572 is an intervening class retransformation or redefinition.
7573 The value of a constant pool entry used by a given bytecode will
7574 match that of the defining class file (even if the indices don't match).
7575 Constant pool entries which are not used directly or indirectly by
7576 bytecodes (for example, UTF-8 strings associated with annotations) are
7577 not required to exist in the returned constant pool.
7578 </description>
7579 <origin>new</origin>
7580 <capabilities>
7581 <required id="can_get_constant_pool"></required>
7582 </capabilities>
7583 <parameters>
7584 <param id="klass">
7585 <jclass/>
7586 <description>
7587 The class to query.
7588 </description>
7589 </param>
7590 <param id="constant_pool_count_ptr">
7591 <outptr><jint/></outptr>
7592 <description>
7593 On return, points to the number of entries
7594 in the constant pool table plus one.
7595 This corresponds to the <code>constant_pool_count</code>
7596 item of the Class File Format.
7597 </description>
7598 </param>
7599 <param id="constant_pool_byte_count_ptr">
7600 <outptr><jint/></outptr>
7601 <description>
7602 On return, points to the number of bytes
7603 in the returned raw constant pool.
7604 </description>
7605 </param>
7606 <param id="constant_pool_bytes_ptr">
7607 <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
7608 <description>
7609 On return, points to the raw constant pool, that is the bytes
7610 defined by the <code>constant_pool</code> item of the
7611 Class File Format
7612 </description>
7613 </param>
7614 </parameters>
7615 <errors>
7616 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7617 The class is a primitive or array class.
7618 </error>
7619 </errors>
7620 </function>
7621
7622 <function id="IsInterface" phase="start" num="55">
7623 <synopsis>Is Interface</synopsis>
7624 <description>
7625 Determines whether a class object reference represents an interface.
7626 The <code>jboolean</code> result is
7627 <code>JNI_TRUE</code> if the "class" is actually an interface,
7628 <code>JNI_FALSE</code> otherwise.
7629 </description>
7630 <origin>jvmdi</origin>
7631 <capabilities>
7632 </capabilities>
7633 <parameters>
7634 <param id="klass">
7635 <jclass/>
7636 <description>
7637 The class to query.
7638 </description>
7639 </param>
7640 <param id="is_interface_ptr">
7641 <outptr><jboolean/></outptr>
7642 <description>
7643 On return, points to the boolean result of this function.
7644
7645 </description>
7646 </param>
7647 </parameters>
7648 <errors>
7649 </errors>
7650 </function>
7651
7652 <function id="IsArrayClass" phase="start" num="56">
7653 <synopsis>Is Array Class</synopsis>
7654 <description>
7655 Determines whether a class object reference represents an array.
7656 The <code>jboolean</code> result is
7657 <code>JNI_TRUE</code> if the class is an array,
7658 <code>JNI_FALSE</code> otherwise.
7659 </description>
7660 <origin>jvmdi</origin>
7661 <capabilities>
7662 </capabilities>
7663 <parameters>
7664 <param id="klass">
7665 <jclass/>
7666 <description>
7667 The class to query.
7668 </description>
7669 </param>
7670 <param id="is_array_class_ptr">
7671 <outptr><jboolean/></outptr>
7672 <description>
7673 On return, points to the boolean result of this function.
7674
7675 </description>
7676 </param>
7677 </parameters>
7678 <errors>
7679 </errors>
7680 </function>
7681
7682 <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
7683 <synopsis>Is Modifiable Class</synopsis>
7684 <description>
7685 Determines whether a class is modifiable.
7686 If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
7687 returns <code>JNI_TRUE</code>) the class can be
7688 redefined with <functionlink id="RedefineClasses"/> (assuming
7689 the agent possesses the
7690 <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
7691 capability) or
7692 retransformed with <functionlink id="RetransformClasses"/> (assuming
7693 the agent possesses the
7694 <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
7695 capability).
7696 If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
7697 returns <code>JNI_FALSE</code>) the class can be neither
7698 redefined nor retransformed.
7699 <p/>
7700 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>),
7701 array classes, and some implementation defined classes are never modifiable.
7702 <p/>
7703 </description>
7704 <origin>new</origin>
7705 <capabilities>
7706 <capability id="can_redefine_any_class">
7707 If possessed then all classes (except primitive, array, and some implementation defined
7708 classes) are modifiable with <functionlink id="RedefineClasses"/>.
7709 </capability>
7710 <capability id="can_retransform_any_class">
7711 If possessed then all classes (except primitive, array, and some implementation defined
7712 classes) are modifiable with <functionlink id="RetransformClasses"/>.
7713 </capability>
7714 <capability id="can_redefine_classes">
7715 No effect on the result of the function.
7716 But must additionally be possessed to modify the class with
7717 <functionlink id="RedefineClasses"/>.
7718 </capability>
7719 <capability id="can_retransform_classes">
7720 No effect on the result of the function.
7721 But must additionally be possessed to modify the class with
7722 <functionlink id="RetransformClasses"/>.
7723 </capability>
7724 </capabilities>
7725 <parameters>
7726 <param id="klass">
7727 <jclass/>
7728 <description>
7729 The class to query.
7730 </description>
7731 </param>
7732 <param id="is_modifiable_class_ptr">
7733 <outptr><jboolean/></outptr>
7734 <description>
7735 On return, points to the boolean result of this function.
7736 </description>
7737 </param>
7738 </parameters>
7739 <errors>
7740 </errors>
7741 </function>
7742
7743 <function id="GetClassLoader" phase="start" num="57">
7744 <synopsis>Get Class Loader</synopsis>
7745 <description>
7746 For the class indicated by <code>klass</code>, return via
7747 <code>classloader_ptr</code> a reference to the class loader for the
7748 class.
7749 </description>
7750 <origin>jvmdi</origin>
7751 <capabilities>
7752 </capabilities>
7753 <parameters>
7754 <param id="klass">
7755 <jclass/>
7756 <description>
7757 The class to query.
7758 </description>
7759 </param>
7760 <param id="classloader_ptr">
7761 <outptr><jobject/></outptr>
7762 <description>
7763 On return, points to the class loader that loaded
7764 this class.
7765 If the class was not created by a class loader
7766 or if the class loader is the bootstrap class loader,
7767 points to <code>NULL</code>.
7768 </description>
7769 </param>
7770 </parameters>
7771 <errors>
7772 </errors>
7773
7774 </function>
7775
7776 <function id="GetSourceDebugExtension" phase="start" num="90">
7777 <synopsis>Get Source Debug Extension</synopsis>
7778 <description>
7779 For the class indicated by <code>klass</code>, return the debug
7780 extension via <code>source_debug_extension_ptr</code>.
7781 The returned string
7782 contains exactly the debug extension information present in the
7783 class file of <code>klass</code>.
7784 </description>
7785 <origin>jvmdi</origin>
7786 <capabilities>
7787 <required id="can_get_source_debug_extension"></required>
7788 </capabilities>
7789 <parameters>
7790 <param id="klass">
7791 <jclass/>
7792 <description>
7793 The class to query.
7794 </description>
7795 </param>
7796 <param id="source_debug_extension_ptr">
7797 <allocbuf><char/></allocbuf>
7798 <description>
7799 On return, points to the class's debug extension, encoded as a
7800 <internallink id="mUTF">modified UTF-8</internallink> string.
7801 </description>
7802 </param>
7803 </parameters>
7804 <errors>
7805 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7806 Class information does not include a debug extension.
7807 </error>
7808 </errors>
7809 </function>
7810
7811 <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7812 <synopsis>Retransform Classes</synopsis>
7813 <description>
7814 This function facilitates the
7815 <internallink id="bci">bytecode instrumentation</internallink>
7816 of already loaded classes.
7817 To replace the class definition without reference to the existing
7818 bytecodes, as one might do when recompiling from source for
7819 fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7820 function should be used instead.
7821 <p/>
7822 When classes are initially loaded or when they are
7823 <functionlink id="RedefineClasses">redefined</functionlink>,
7824 the initial class file bytes can be transformed with the
7825 <eventlink id="ClassFileLoadHook"/> event.
7826 This function reruns the transformation process
7827 (whether or not a transformation has previously occurred).
7828 This retransformation follows these steps:
7829 <ul>
7830 <li>starting from the initial class file bytes
7831 </li>
7832 <li>for each <fieldlink id="can_retransform_classes"
7833 struct="jvmtiCapabilities">retransformation
7834 incapable</fieldlink>
7835 agent which received a
7836 <code>ClassFileLoadHook</code> event during the previous
7837 load or redefine, the bytes it returned
7838 (via the <code>new_class_data</code> parameter)
7839 are reused as the output of the transformation;
7840 note that this is equivalent to reapplying
7841 the previous transformation, unaltered. except that
7842 the <code>ClassFileLoadHook</code> event
7843 is <b>not</b> sent to these agents
7844 </li>
7845 <li>for each <fieldlink id="can_retransform_classes"
7846 struct="jvmtiCapabilities">retransformation
7847 capable</fieldlink>
7848 agent, the <code>ClassFileLoadHook</code> event is sent,
7849 allowing a new transformation to be applied
7850 </li>
7851 <li>the transformed class file bytes are installed as the new
7852 definition of the class
7853 </li>
7854 </ul>
7855 See the <eventlink id="ClassFileLoadHook"/> event for more details.
7856 <p/>
7857 The initial class file bytes represent the bytes passed to
7858 <code>ClassLoader.defineClass</code>
7859 or <code>RedefineClasses</code> (before any transformations
7860 were applied), however they may not exactly match them.
7861 The constant pool may differ in ways described in
7862 <functionlink id="GetConstantPool"/>.
7863 Constant pool indices in the bytecodes of methods will correspond.
7864 Some attributes may not be present.
7865 Where order is not meaningful, for example the order of methods,
7866 order may not be preserved.
7867 <p/>
7868 Retransformation can cause new versions of methods to be installed.
7869 Old method versions may become
7870 <internallink id="obsoleteMethods">obsolete</internallink>
7871 The new method version will be used on new invokes.
7872 If a method has active stack frames, those active frames continue to
7873 run the bytecodes of the original method version.
7874 <p/>
7875 This function does not cause any initialization except that which
7876 would occur under the customary JVM semantics.
7877 In other words, retransforming a class does not cause its initializers to be
7878 run. The values of static fields will remain as they were
7879 prior to the call.
7880 <p/>
7881 Threads need not be suspended.
7882 <p/>
7883 All breakpoints in the class are cleared.
7884 <p/>
7885 All attributes are updated.
7886 <p/>
7887 Instances of the retransformed class are not affected -- fields retain their
7888 previous values.
7889 <functionlink id="GetTag">Tags</functionlink> on the instances are
7890 also unaffected.
7891 <p/>
7892 In response to this call, no events other than the
7893 <eventlink id="ClassFileLoadHook"/> event
7894 will be sent.
7895 <p/>
7896 The retransformation may change method bodies, the constant pool and attributes
7897 (unless explicitly prohibited).
7898 The retransformation must not add, remove or rename fields or methods, change the
7899 signatures of methods, change modifiers, or change inheritance.
7900 The retransformation must not change the <code>NestHost</code>,
7901 <code>NestMembers</code>, <code>Record</code>, or <code>PermittedSubclasses</code>
7902 attributes.
7903 These restrictions may be lifted in future versions.
7904 See the error return description below for information on error codes
7905 returned if an unsupported retransformation is attempted.
7906 The class file bytes are not verified or installed until they have passed
7907 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7908 returned error code reflects the result of the transformations.
7909 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7910 none of the classes to be retransformed will have a new definition installed.
7911 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7912 all of the classes to be retransformed will have their new definitions installed.
7913 </description>
7914 <origin>new</origin>
7915 <capabilities>
7916 <required id="can_retransform_classes"></required>
7917 <capability id="can_retransform_any_class"></capability>
7918 </capabilities>
7919 <parameters>
7920 <param id="class_count">
7921 <jint min="0"/>
7922 <description>
7923 The number of classes to be retransformed.
7924 </description>
7925 </param>
7926 <param id="classes">
7927 <inbuf incount="class_count"><jclass/></inbuf>
7928 <description>
7929 The array of classes to be retransformed.
7930 </description>
7931 </param>
7932 </parameters>
7933 <errors>
7934 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7935 One of the <paramlink id="classes"/> cannot be modified.
7936 See <functionlink id="IsModifiableClass"/>.
7937 </error>
7938 <error id="JVMTI_ERROR_INVALID_CLASS">
7939 One of the <paramlink id="classes"/> is not a valid class.
7940 </error>
7941 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7942 A retransformed class file has a version number not supported by this VM.
7943 </error>
7944 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7945 A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
7946 </error>
7947 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7948 The retransformed class file definitions would lead to a circular definition
7949 (the VM would return a <code>ClassCircularityError</code>).
7950 </error>
7951 <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7952 The retransformed class file bytes fail verification.
7953 </error>
7954 <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7955 The class name defined in a retransformed class file is
7956 different from the name in the old class object.
7957 </error>
7958 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7959 A retransformed class file would require adding a method.
7960 </error>
7961 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7962 A retransformed class file changes a field.
7963 </error>
7964 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7965 A direct superclass is different for a retransformed class file,
7966 or the set of directly implemented
7967 interfaces is different.
7968 </error>
7969 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7970 A retransformed class file does not declare a method
7971 declared in the old class version.
7972 </error>
7973 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED">
7974 A retransformed class file has unsupported differences in class attributes.
7975 </error>
7976 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7977 A retransformed class file has different class modifiers.
7978 </error>
7979 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7980 A method in the retransformed class file has different modifiers
7981 than its counterpart in the old class version.
7982 </error>
7983 </errors>
7984 </function>
7985
7986 <function id="RedefineClasses" jkernel="yes" num="87">
7987 <synopsis>Redefine Classes</synopsis>
7988 <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7989 <field id="klass">
7990 <jclass/>
7991 <description>
7992 Class object for this class
7993 </description>
7994 </field>
7995 <field id="class_byte_count">
7996 <jint/>
7997 <description>
7998 Number of bytes defining class (below)
7999 </description>
8000 </field>
8001 <field id="class_bytes">
8002 <inbuf incount="class_byte_count"><uchar/></inbuf>
8003 <description>
8004 Bytes defining class (in <vmspec chapter="4"/>)
8005 </description>
8006 </field>
8007 </typedef>
8008 <description>
8009 All classes given are redefined according to the definitions
8010 supplied.
8011 This function is used to replace the definition of a class
8012 with a new definition, as might be needed in fix-and-continue
8013 debugging.
8014 Where the existing class file bytes are to be transformed, for
8015 example in
8016 <internallink id="bci">bytecode instrumentation</internallink>,
8017 <functionlink id="RetransformClasses"/> should be used.
8018 <p/>
8019 Redefinition can cause new versions of methods to be installed.
8020 Old method versions may become
8021 <internallink id="obsoleteMethods">obsolete</internallink>
8022 The new method version will be used on new invokes.
8023 If a method has active stack frames, those active frames continue to
8024 run the bytecodes of the original method version.
8025 If resetting of stack frames is desired, use
8026 <functionlink id="PopFrame"></functionlink>
8027 to pop frames with obsolete method versions.
8028 <p/>
8029 This function does not cause any initialization except that which
8030 would occur under the customary JVM semantics.
8031 In other words, redefining a class does not cause its initializers to be
8032 run. The values of static fields will remain as they were
8033 prior to the call.
8034 <p/>
8035 Threads need not be suspended.
8036 <p/>
8037 All breakpoints in the class are cleared.
8038 <p/>
8039 All attributes are updated.
8040 <p/>
8041 Instances of the redefined class are not affected -- fields retain their
8042 previous values.
8043 <functionlink id="GetTag">Tags</functionlink> on the instances are
8044 also unaffected.
8045 <p/>
8046 In response to this call, the <jvmti/> event
8047 <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
8048 will be sent (if enabled), but no other <jvmti/> events will be sent.
8049 <p/>
8050 The redefinition may change method bodies, the constant pool and attributes
8051 (unless explicitly prohibited).
8052 The redefinition must not add, remove or rename fields or methods, change the
8053 signatures of methods, change modifiers, or change inheritance.
8054 The redefinition must not change the <code>NestHost</code>,
8055 <code>NestMembers</code>, <code>Record</code>, or <code>PermittedSubclasses</code>
8056 attributes.
8057 These restrictions may be lifted in future versions.
8058 See the error return description below for information on error codes
8059 returned if an unsupported redefinition is attempted.
8060 The class file bytes are not verified or installed until they have passed
8061 through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
8062 returned error code reflects the result of the transformations applied
8063 to the bytes passed into <paramlink id="class_definitions"/>.
8064 If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
8065 none of the classes to be redefined will have a new definition installed.
8066 When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
8067 all of the classes to be redefined will have their new definitions installed.
8068 </description>
8069 <origin>jvmdi</origin>
8070 <capabilities>
8071 <required id="can_redefine_classes"></required>
8072 <capability id="can_redefine_any_class"></capability>
8073 </capabilities>
8074 <parameters>
8075 <param id="class_count">
8076 <jint min="0"/>
8077 <description>
8078 The number of classes specified in <code>class_definitions</code>
8079 </description>
8080 </param>
8081 <param id="class_definitions">
8082 <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
8083 <description>
8084 The array of new class definitions
8085 </description>
8086 </param>
8087 </parameters>
8088 <errors>
8089 <error id="JVMTI_ERROR_NULL_POINTER">
8090 One of <code>class_bytes</code> is <code>NULL</code>.
8091 </error>
8092 <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
8093 An element of <code>class_definitions</code> cannot be modified.
8094 See <functionlink id="IsModifiableClass"/>.
8095 </error>
8096 <error id="JVMTI_ERROR_INVALID_CLASS">
8097 An element of <code>class_definitions</code> is not a valid class.
8098 </error>
8099 <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
8100 A new class file has a version number not supported by this VM.
8101 </error>
8102 <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
8103 A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
8104 </error>
8105 <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
8106 The new class file definitions would lead to a circular definition
8107 (the VM would return a <code>ClassCircularityError</code>).
8108 </error>
8109 <error id="JVMTI_ERROR_FAILS_VERIFICATION">
8110 The class bytes fail verification.
8111 </error>
8112 <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
8113 The class name defined in a new class file is
8114 different from the name in the old class object.
8115 </error>
8116 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
8117 A new class file would require adding a method.
8118 </error>
8119 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
8120 A new class version changes a field.
8121 </error>
8122 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
8123 A direct superclass is different for a new class
8124 version, or the set of directly implemented
8125 interfaces is different.
8126 </error>
8127 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
8128 A new class version does not declare a method
8129 declared in the old class version.
8130 </error>
8131 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED">
8132 A new class version has unsupported differences in class attributes.
8133 </error>
8134 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
8135 A new class version has different modifiers.
8136 </error>
8137 <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
8138 A method in the new class version has different modifiers
8139 than its counterpart in the old class version.
8140 </error>
8141 <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
8142 A module cannot be modified.
8143 See <functionlink id="IsModifiableModule"/>.
8144 </error>
8145 </errors>
8146 </function>
8147
8148 </category>
8149
8150 <category id="object" label="Object">
8151
8152 <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
8153 <synopsis>Get Object Size</synopsis>
8154 <description>
8155 For the object indicated by <code>object</code>,
8156 return via <code>size_ptr</code> the size of the object.
8157 This size is an implementation-specific approximation of
8158 the amount of storage consumed by this object.
8159 It may include some or all of the object's overhead, and thus
8160 is useful for comparison within an implementation but not
8161 between implementations.
8162 The estimate may change during a single invocation of the JVM.
8163 </description>
8164 <origin>new</origin>
8165 <capabilities>
8166 </capabilities>
8167 <parameters>
8168 <param id="object">
8169 <jobject/>
8170 <description>
8171 The object to query.
8172 </description>
8173 </param>
8174 <param id="size_ptr">
8175 <outptr><jlong/></outptr>
8176 <description>
8177 On return, points to the object's size in bytes.
8178 </description>
8179 </param>
8180 </parameters>
8181 <errors>
8182 </errors>
8183 </function>
8184
8185 <function id="GetObjectHashCode" phase="start" num="58">
8186 <synopsis>Get Object Hash Code</synopsis>
8187 <description>
8188 For the object indicated by <code>object</code>,
8189 return via <code>hash_code_ptr</code> a hash code.
8190 This hash code could be used to maintain a hash table of object references,
8191 however, on some implementations this can cause significant performance
8192 impacts--in most cases
8193 <internallink id="Heap">tags</internallink>
8194 will be a more efficient means of associating information with objects.
8195 This function guarantees
8196 the same hash code value for a particular object throughout its life
8197 </description>
8198 <origin>jvmdi</origin>
8199 <capabilities>
8200 </capabilities>
8201 <parameters>
8202 <param id="object">
8203 <jobject/>
8204 <description>
8205 The object to query.
8206 </description>
8207 </param>
8208 <param id="hash_code_ptr">
8209 <outptr><jint/></outptr>
8210 <description>
8211 On return, points to the object's hash code.
8212 </description>
8213 </param>
8214 </parameters>
8215 <errors>
8216 </errors>
8217 </function>
8218
8219 <function id="GetObjectMonitorUsage" num="59">
8220 <synopsis>Get Object Monitor Usage</synopsis>
8221 <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
8222 <field id="owner">
8223 <jthread/>
8224 <description>
8225 The thread owning this monitor, or <code>NULL</code> if unused
8226 </description>
8227 </field>
8228 <field id="entry_count">
8229 <jint/>
8230 <description>
8231 The number of times the owning thread has entered the monitor
8232 </description>
8233 </field>
8234 <field id="waiter_count">
8235 <jint/>
8236 <description>
8237 The number of threads waiting to own this monitor
8238 </description>
8239 </field>
8240 <field id="waiters">
8241 <allocfieldbuf><jthread/></allocfieldbuf>
8242 <description>
8243 The <code>waiter_count</code> waiting threads
8244 </description>
8245 </field>
8246 <field id="notify_waiter_count">
8247 <jint/>
8248 <description>
8249 The number of threads waiting to be notified by this monitor
8250 </description>
8251 </field>
8252 <field id="notify_waiters">
8253 <allocfieldbuf><jthread/></allocfieldbuf>
8254 <description>
8255 The <code>notify_waiter_count</code> threads waiting to be notified
8256 </description>
8257 </field>
8258 </typedef>
8259 <description>
8260 Get information about the object's monitor.
8261 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
8262 are filled in with information about usage of the monitor.
8263 <todo>
8264 Decide and then clarify suspend requirements.
8265 </todo>
8266 </description>
8267 <origin>jvmdi</origin>
8268 <capabilities>
8269 <required id="can_get_monitor_info"></required>
8270 </capabilities>
8271 <parameters>
8272 <param id="object">
8273 <jobject/>
8274 <description>
8275 The object to query.
8276 </description>
8277 </param>
8278 <param id="info_ptr">
8279 <outptr><struct>jvmtiMonitorUsage</struct></outptr>
8280 <description>
8281 On return, filled with monitor information for the
8282 specified object.
8283 </description>
8284 </param>
8285 </parameters>
8286 <errors>
8287 </errors>
8288 </function>
8289
8290 <elide>
8291 <function id="GetObjectMonitors" num="116">
8292 <synopsis>Get Object Monitors</synopsis>
8293 <description>
8294 Return the list of object monitors.
8295 <p/>
8296 Note: details about each monitor can be examined with
8297 <functionlink id="GetObjectMonitorUsage"></functionlink>.
8298 </description>
8299 <origin>new</origin>
8300 <capabilities>
8301 <required id="can_get_monitor_info"></required>
8302 </capabilities>
8303 <parameters>
8304 <param id="monitorCnt">
8305 <outptr><jint/></outptr>
8306 <description>
8307 On return, pointer to the number
8308 of monitors returned in <code>monitors_ptr</code>.
8309 </description>
8310 </param>
8311 <param id="monitors_ptr">
8312 <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
8313 <description>
8314 On return, pointer to the monitor list.
8315 </description>
8316 </param>
8317 </parameters>
8318 <errors>
8319 </errors>
8320 </function>
8321 </elide>
8322
8323 </category>
8324
8325 <category id="fieldCategory" label="Field">
8326
8327 <intro>
8328 </intro>
8329
8330 <function id="GetFieldName" phase="start" num="60">
8331 <synopsis>Get Field Name (and Signature)</synopsis>
8332 <description>
8333 For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
8334 return the field name via <paramlink id="name_ptr"/> and field signature via
8335 <paramlink id="signature_ptr"/>.
8336 <p/>
8337 Field signatures are defined in the
8338 <externallink id="jni/index.html">JNI Specification</externallink>
8339 and are referred to as <code>field descriptors</code> in
8340 <vmspec chapter="4.3.2"/>.
8341 </description>
8342 <origin>jvmdiClone</origin>
8343 <capabilities>
8344 </capabilities>
8345 <parameters>
8346 <param id="klass">
8347 <jclass field="field"/>
8348 <description>
8349 The class of the field to query.
8350 </description>
8351 </param>
8352 <param id="field">
8353 <jfieldID class="klass"/>
8354 <description>
8355 The field to query.
8356 </description>
8357 </param>
8358 <param id="name_ptr">
8359 <allocbuf>
8360 <char/>
8361 <nullok>the name is not returned</nullok>
8362 </allocbuf>
8363 <description>
8364 On return, points to the field name, encoded as a
8365 <internallink id="mUTF">modified UTF-8</internallink> string.
8366 </description>
8367 </param>
8368 <param id="signature_ptr">
8369 <allocbuf>
8370 <char/>
8371 <nullok>the signature is not returned</nullok>
8372 </allocbuf>
8373 <description>
8374 On return, points to the field signature, encoded as a
8375 <internallink id="mUTF">modified UTF-8</internallink> string.
8376 </description>
8377 </param>
8378 <param id="generic_ptr">
8379 <allocbuf>
8380 <char/>
8381 <nullok>the generic signature is not returned</nullok>
8382 </allocbuf>
8383 <description>
8384 On return, points to the generic signature of the field, encoded as a
8385 <internallink id="mUTF">modified UTF-8</internallink> string.
8386 If there is no generic signature attribute for the field, then,
8387 on return, points to <code>NULL</code>.
8388 </description>
8389 </param>
8390 </parameters>
8391 <errors>
8392 </errors>
8393 </function>
8394
8395 <function id="GetFieldDeclaringClass" phase="start" num="61">
8396 <synopsis>Get Field Declaring Class</synopsis>
8397 <description>
8398 For the field indicated by <code>klass</code> and <code>field</code>
8399 return the class that defined it via <code>declaring_class_ptr</code>.
8400 The declaring class will either be <code>klass</code>, a superclass, or
8401 an implemented interface.
8402 </description>
8403 <origin>jvmdi</origin>
8404 <capabilities>
8405 </capabilities>
8406 <parameters>
8407 <param id="klass">
8408 <jclass field="field"/>
8409 <description>
8410 The class to query.
8411 </description>
8412 </param>
8413 <param id="field">
8414 <jfieldID class="klass"/>
8415 <description>
8416 The field to query.
8417 </description>
8418 </param>
8419 <param id="declaring_class_ptr">
8420 <outptr><jclass/></outptr>
8421 <description>
8422 On return, points to the declaring class
8423 </description>
8424 </param>
8425 </parameters>
8426 <errors>
8427 </errors>
8428 </function>
8429
8430 <function id="GetFieldModifiers" phase="start" num="62">
8431 <synopsis>Get Field Modifiers</synopsis>
8432 <description>
8433 For the field indicated by <code>klass</code> and <code>field</code>
8434 return the access flags via <code>modifiers_ptr</code>.
8435 Access flags are defined in <vmspec chapter="4"/>.
8436 </description>
8437 <origin>jvmdi</origin>
8438 <capabilities>
8439 </capabilities>
8440 <parameters>
8441 <param id="klass">
8442 <jclass field="field"/>
8443 <description>
8444 The class to query.
8445 </description>
8446 </param>
8447 <param id="field">
8448 <jfieldID class="klass"/>
8449 <description>
8450 The field to query.
8451 </description>
8452 </param>
8453 <param id="modifiers_ptr">
8454 <outptr><jint/></outptr>
8455 <description>
8456 On return, points to the access flags.
8457 </description>
8458 </param>
8459 </parameters>
8460 <errors>
8461 </errors>
8462 </function>
8463
8464 <function id="IsFieldSynthetic" phase="start" num="63">
8465 <synopsis>Is Field Synthetic</synopsis>
8466 <description>
8467 For the field indicated by <code>klass</code> and <code>field</code>, return a
8468 value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
8469 Synthetic fields are generated by the compiler but not present in the
8470 original source code.
8471 </description>
8472 <origin>jvmdi</origin>
8473 <capabilities>
8474 <required id="can_get_synthetic_attribute"></required>
8475 </capabilities>
8476 <parameters>
8477 <param id="klass">
8478 <jclass field="field"/>
8479 <description>
8480 The class of the field to query.
8481 </description>
8482 </param>
8483 <param id="field">
8484 <jfieldID class="klass"/>
8485 <description>
8486 The field to query.
8487 </description>
8488 </param>
8489 <param id="is_synthetic_ptr">
8490 <outptr><jboolean/></outptr>
8491 <description>
8492 On return, points to the boolean result of this function.
8493 </description>
8494 </param>
8495 </parameters>
8496 <errors>
8497 </errors>
8498 </function>
8499
8500 </category>
8501
8502 <category id="method" label="Method">
8503
8504 <intro>
8505 These functions provide information about a method (represented as a
8506 <typelink id="jmethodID"/>) and set how methods are processed.
8507 </intro>
8508
8509 <intro id="obsoleteMethods" label="Obsolete Methods">
8510 The functions <functionlink id="RetransformClasses"/> and
8511 <functionlink id="RedefineClasses"/> can cause new versions
8512 of methods to be installed.
8513 An original version of a method is considered equivalent
8514 to the new version if:
8515 <ul>
8516 <li>their bytecodes are the same except for indices into the
8517 constant pool and </li>
8518 <li>the referenced constants are equal.</li>
8519 </ul>
8520 An original method version which is not equivalent to the
8521 new method version is called obsolete and is assigned a new method ID;
8522 the original method ID now refers to the new method version.
8523 A method ID can be tested for obsolescence with
8524 <functionlink id="IsMethodObsolete"/>.
8525 </intro>
8526
8527 <function id="GetMethodName" phase="start" num="64">
8528 <synopsis>Get Method Name (and Signature)</synopsis>
8529 <description>
8530 For the method indicated by <code>method</code>,
8531 return the method name via <code>name_ptr</code> and method signature via
8532 <code>signature_ptr</code>.
8533 <p/>
8534 Method signatures are defined in the
8535 <externallink id="jni/index.html">JNI Specification</externallink>
8536 and are referred to as <code>method descriptors</code> in
8537 <vmspec chapter="4.3.3"/>.
8538 Note this is different
8539 than method signatures as defined in the <i>Java Language Specification</i>.
8540 </description>
8541 <origin>jvmdiClone</origin>
8542 <capabilities>
8543 </capabilities>
8544 <parameters>
8545 <param id="method">
8546 <jmethodID/>
8547 <description>
8548 The method to query.
8549 </description>
8550 </param>
8551 <param id="name_ptr">
8552 <allocbuf>
8553 <char/>
8554 <nullok>the name is not returned</nullok>
8555 </allocbuf>
8556 <description>
8557 On return, points to the method name, encoded as a
8558 <internallink id="mUTF">modified UTF-8</internallink> string.
8559 </description>
8560 </param>
8561 <param id="signature_ptr">
8562 <allocbuf>
8563 <char/>
8564 <nullok>the signature is not returned</nullok>
8565 </allocbuf>
8566 <description>
8567 On return, points to the method signature, encoded as a
8568 <internallink id="mUTF">modified UTF-8</internallink> string.
8569 </description>
8570 </param>
8571 <param id="generic_ptr">
8572 <allocbuf>
8573 <char/>
8574 <nullok>the generic signature is not returned</nullok>
8575 </allocbuf>
8576 <description>
8577 On return, points to the generic signature of the method, encoded as a
8578 <internallink id="mUTF">modified UTF-8</internallink> string.
8579 If there is no generic signature attribute for the method, then,
8580 on return, points to <code>NULL</code>.
8581 </description>
8582 </param>
8583 </parameters>
8584 <errors>
8585 </errors>
8586 </function>
8587
8588 <function id="GetMethodDeclaringClass" phase="start" num="65">
8589 <synopsis>Get Method Declaring Class</synopsis>
8590 <description>
8591 For the method indicated by <code>method</code>,
8592 return the class that defined it via <code>declaring_class_ptr</code>.
8593 </description>
8594 <origin>jvmdi</origin>
8595 <capabilities>
8596 </capabilities>
8597 <parameters>
8598 <param id="klass">
8599 <jclass method="method"/>
8600 <description>
8601 The class to query.
8602 </description>
8603 </param>
8604 <param id="method">
8605 <jmethodID class="klass"/>
8606 <description>
8607 The method to query.
8608 </description>
8609 </param>
8610 <param id="declaring_class_ptr">
8611 <outptr><jclass/></outptr>
8612 <description>
8613 On return, points to the declaring class
8614 </description>
8615 </param>
8616 </parameters>
8617 <errors>
8618 </errors>
8619 </function>
8620
8621 <function id="GetMethodModifiers" phase="start" num="66">
8622 <synopsis>Get Method Modifiers</synopsis>
8623 <description>
8624 For the method indicated by <code>method</code>,
8625 return the access flags via <code>modifiers_ptr</code>.
8626 Access flags are defined in <vmspec chapter="4"/>.
8627 </description>
8628 <origin>jvmdi</origin>
8629 <capabilities>
8630 </capabilities>
8631 <parameters>
8632 <param id="klass">
8633 <jclass method="method"/>
8634 <description>
8635 The class to query.
8636 </description>
8637 </param>
8638 <param id="method">
8639 <jmethodID class="klass"/>
8640 <description>
8641 The method to query.
8642 </description>
8643 </param>
8644 <param id="modifiers_ptr">
8645 <outptr><jint/></outptr>
8646 <description>
8647 On return, points to the access flags.
8648 </description>
8649 </param>
8650 </parameters>
8651 <errors>
8652 </errors>
8653 </function>
8654
8655 <function id="GetMaxLocals" phase="start" num="68">
8656 <synopsis>Get Max Locals</synopsis>
8657 <description>
8658 For the method indicated by <code>method</code>,
8659 return the number of local variable slots used by the method,
8660 including the local variables used to pass parameters to the
8661 method on its invocation.
8662 <p/>
8663 See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
8664 </description>
8665 <origin>jvmdi</origin>
8666 <capabilities>
8667 </capabilities>
8668 <parameters>
8669 <param id="klass">
8670 <jclass method="method"/>
8671 <description>
8672 The class to query.
8673 </description>
8674 </param>
8675 <param id="method">
8676 <jmethodID class="klass" native="error"/>
8677 <description>
8678 The method to query.
8679 </description>
8680 </param>
8681 <param id="max_ptr">
8682 <outptr><jint/></outptr>
8683 <description>
8684 On return, points to the maximum number of local slots
8685 </description>
8686 </param>
8687 </parameters>
8688 <errors>
8689 </errors>
8690 </function>
8691
8692 <function id="GetArgumentsSize" phase="start" num="69">
8693 <synopsis>Get Arguments Size</synopsis>
8694 <description>
8695 For the method indicated by <code>method</code>,
8696 return via <code>max_ptr</code> the number of local variable slots used
8697 by the method's arguments.
8698 Note that two-word arguments use two slots.
8699 </description>
8700 <origin>jvmdi</origin>
8701 <capabilities>
8702 </capabilities>
8703 <parameters>
8704 <param id="klass">
8705 <jclass method="method"/>
8706 <description>
8707 The class to query.
8708 </description>
8709 </param>
8710 <param id="method">
8711 <jmethodID class="klass" native="error"/>
8712 <description>
8713 The method to query.
8714 </description>
8715 </param>
8716 <param id="size_ptr">
8717 <outptr><jint/></outptr>
8718 <description>
8719 On return, points to the number of argument slots
8720 </description>
8721 </param>
8722 </parameters>
8723 <errors>
8724 </errors>
8725 </function>
8726
8727 <function id="GetLineNumberTable" phase="start" num="70">
8728 <synopsis>Get Line Number Table</synopsis>
8729 <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
8730 <field id="start_location">
8731 <jlocation/>
8732 <description>
8733 the <datalink id="jlocation"></datalink> where the line begins
8734 </description>
8735 </field>
8736 <field id="line_number">
8737 <jint/>
8738 <description>
8739 the line number
8740 </description>
8741 </field>
8742 </typedef>
8743 <description>
8744 For the method indicated by <code>method</code>,
8745 return a table of source line number entries. The size of the table is
8746 returned via <code>entry_count_ptr</code> and the table itself is
8747 returned via <code>table_ptr</code>.
8748 </description>
8749 <origin>jvmdi</origin>
8750 <capabilities>
8751 <required id="can_get_line_numbers"></required>
8752 </capabilities>
8753 <parameters>
8754 <param id="klass">
8755 <jclass method="method"/>
8756 <description>
8757 The class to query.
8758 </description>
8759 </param>
8760 <param id="method">
8761 <jmethodID class="klass" native="error"/>
8762 <description>
8763 The method to query.
8764 </description>
8765 </param>
8766 <param id="entry_count_ptr">
8767 <outptr><jint/></outptr>
8768 <description>
8769 On return, points to the number of entries in the table
8770 </description>
8771 </param>
8772 <param id="table_ptr">
8773 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8774 <description>
8775 On return, points to the line number table pointer.
8776 </description>
8777 </param>
8778 </parameters>
8779 <errors>
8780 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8781 Class information does not include line numbers.
8782 </error>
8783 </errors>
8784 </function>
8785
8786 <function id="GetMethodLocation" phase="start" num="71">
8787 <synopsis>Get Method Location</synopsis>
8788 <description>
8789 For the method indicated by <code>method</code>,
8790 return the beginning and ending addresses through
8791 <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8792 conventional bytecode indexing scheme,
8793 <code>start_location_ptr</code> will always point to zero
8794 and <code>end_location_ptr</code>
8795 will always point to the bytecode count minus one.
8796 </description>
8797 <origin>jvmdi</origin>
8798 <capabilities>
8799 </capabilities>
8800 <parameters>
8801 <param id="klass">
8802 <jclass method="method"/>
8803 <description>
8804 The class to query.
8805 </description>
8806 </param>
8807 <param id="method">
8808 <jmethodID class="klass" native="error"/>
8809 <description>
8810 The method to query.
8811 </description>
8812 </param>
8813 <param id="start_location_ptr">
8814 <outptr><jlocation/></outptr>
8815 <description>
8816 On return, points to the first location, or
8817 <code>-1</code> if location information is not available.
8818 If the information is available and
8819 <functionlink id="GetJLocationFormat"></functionlink>
8820 returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8821 then this will always be zero.
8822 </description>
8823 </param>
8824 <param id="end_location_ptr">
8825 <outptr><jlocation/></outptr>
8826 <description>
8827 On return, points to the last location,
8828 or <code>-1</code> if location information is not available.
8829 </description>
8830 </param>
8831 </parameters>
8832 <errors>
8833 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8834 Class information does not include method sizes.
8835 </error>
8836 </errors>
8837 </function>
8838
8839 <function id="GetLocalVariableTable" num="72">
8840 <synopsis>Get Local Variable Table</synopsis>
8841 <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8842 <field id="start_location">
8843 <jlocation/>
8844 <description>
8845 The code array index where the local variable is first valid
8846 (that is, where it must have a value).
8847 </description>
8848 </field>
8849 <field id="length">
8850 <jint/>
8851 <description>
8852 The length of the valid section for this local variable.
8853 The last code array index where the local variable is valid
8854 is <code>start_location + length</code>.
8855 </description>
8856 </field>
8857 <field id="name">
8858 <allocfieldbuf><char/></allocfieldbuf>
8859 <description>
8860 The local variable name, encoded as a
8861 <internallink id="mUTF">modified UTF-8</internallink> string.
8862 </description>
8863 </field>
8864 <field id="signature">
8865 <allocfieldbuf><char/></allocfieldbuf>
8866 <description>
8867 The local variable's type signature, encoded as a
8868 <internallink id="mUTF">modified UTF-8</internallink> string.
8869 The signature format is the same as that defined in
8870 <vmspec chapter="4.3.2"/>.
8871 </description>
8872 </field>
8873 <field id="generic_signature">
8874 <allocfieldbuf><char/></allocfieldbuf>
8875 <description>
8876 The local variable's generic signature, encoded as a
8877 <internallink id="mUTF">modified UTF-8</internallink> string.
8878 The value of this field will be <code>NULL</code> for any local
8879 variable which does not have a generic type.
8880 </description>
8881 </field>
8882 <field id="slot">
8883 <jint/>
8884 <description>
8885 The local variable's slot. See <internallink id="local">Local Variables</internallink>.
8886 </description>
8887 </field>
8888 </typedef>
8889 <description>
8890 Return local variable information.
8891 </description>
8892 <origin>jvmdiClone</origin>
8893 <capabilities>
8894 <required id="can_access_local_variables"></required>
8895 </capabilities>
8896 <parameters>
8897 <param id="method">
8898 <jmethodID native="error"/>
8899 <description>
8900 The method to query.
8901 </description>
8902 </param>
8903 <param id="entry_count_ptr">
8904 <outptr><jint/></outptr>
8905 <description>
8906 On return, points to the number of entries in the table
8907 </description>
8908 </param>
8909 <param id="table_ptr">
8910 <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8911 <description>
8912 On return, points to an array of local variable table entries.
8913 </description>
8914 </param>
8915 </parameters>
8916 <errors>
8917 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8918 Class information does not include local variable
8919 information.
8920 </error>
8921 </errors>
8922 </function>
8923
8924 <function id="GetBytecodes" phase="start" num="75">
8925 <synopsis>Get Bytecodes</synopsis>
8926 <description>
8927 For the method indicated by <code>method</code>,
8928 return the bytecodes that implement the method. The number of
8929 bytecodes is returned via <code>bytecode_count_ptr</code>. The bytecodes
8930 themselves are returned via <code>bytecodes_ptr</code>.
8931 </description>
8932 <origin>jvmdi</origin>
8933 <capabilities>
8934 <required id="can_get_bytecodes"></required>
8935 </capabilities>
8936 <parameters>
8937 <param id="klass">
8938 <jclass method="method"/>
8939 <description>
8940 The class to query.
8941 </description>
8942 </param>
8943 <param id="method">
8944 <jmethodID class="klass" native="error"/>
8945 <description>
8946 The method to query.
8947 </description>
8948 </param>
8949 <param id="bytecode_count_ptr">
8950 <outptr><jint/></outptr>
8951 <description>
8952 On return, points to the length of the bytecode array
8953 </description>
8954 </param>
8955 <param id="bytecodes_ptr">
8956 <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8957 <description>
8958 On return, points to the pointer to the bytecode array
8959 </description>
8960 </param>
8961 </parameters>
8962 <errors>
8963 </errors>
8964 </function>
8965
8966 <function id="IsMethodNative" phase="start" num="76">
8967 <synopsis>Is Method Native</synopsis>
8968 <description>
8969 For the method indicated by <code>method</code>, return a
8970 value indicating whether the method is native via <code>is_native_ptr</code>
8971 </description>
8972 <origin>jvmdi</origin>
8973 <capabilities>
8974 </capabilities>
8975 <parameters>
8976 <param id="klass">
8977 <jclass method="method"/>
8978 <description>
8979 The class to query.
8980 </description>
8981 </param>
8982 <param id="method">
8983 <jmethodID class="klass"/>
8984 <description>
8985 The method to query.
8986 </description>
8987 </param>
8988 <param id="is_native_ptr">
8989 <outptr><jboolean/></outptr>
8990 <description>
8991 On return, points to the boolean result of this function.
8992 </description>
8993 </param>
8994 </parameters>
8995 <errors>
8996 </errors>
8997 </function>
8998
8999 <function id="IsMethodSynthetic" phase="start" num="77">
9000 <synopsis>Is Method Synthetic</synopsis>
9001 <description>
9002 For the method indicated by <code>method</code>, return a
9003 value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
9004 Synthetic methods are generated by the compiler but not present in the
9005 original source code.
9006 </description>
9007 <origin>jvmdi</origin>
9008 <capabilities>
9009 <required id="can_get_synthetic_attribute"></required>
9010 </capabilities>
9011 <parameters>
9012 <param id="klass">
9013 <jclass method="method"/>
9014 <description>
9015 The class to query.
9016 </description>
9017 </param>
9018 <param id="method">
9019 <jmethodID class="klass"/>
9020 <description>
9021 The method to query.
9022 </description>
9023 </param>
9024 <param id="is_synthetic_ptr">
9025 <outptr><jboolean/></outptr>
9026 <description>
9027 On return, points to the boolean result of this function.
9028 </description>
9029 </param>
9030 </parameters>
9031 <errors>
9032 </errors>
9033 </function>
9034
9035 <function id="IsMethodObsolete" phase="start" num="91">
9036 <synopsis>Is Method Obsolete</synopsis>
9037 <description>
9038 Determine if a method ID refers to an
9039 <internallink id="obsoleteMethods">obsolete</internallink>
9040 method version.
9041 </description>
9042 <origin>jvmdi</origin>
9043 <capabilities>
9044 </capabilities>
9045 <parameters>
9046 <param id="klass">
9047 <jclass method="method"/>
9048 <description>
9049 The class to query.
9050 </description>
9051 </param>
9052 <param id="method">
9053 <jmethodID class="klass"/>
9054 <description>
9055 The method ID to query.
9056 </description>
9057 </param>
9058 <param id="is_obsolete_ptr">
9059 <outptr><jboolean/></outptr>
9060 <description>
9061 On return, points to the boolean result of this function.
9062 </description>
9063 </param>
9064 </parameters>
9065 <errors>
9066 </errors>
9067 </function>
9068
9069 <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
9070 <synopsis>Set Native Method Prefix</synopsis>
9071 <description>
9072 This function modifies the failure handling of
9073 native method resolution by allowing retry
9074 with a prefix applied to the name.
9075 When used with the
9076 <eventlink id="ClassFileLoadHook">ClassFileLoadHook
9077 event</eventlink>, it enables native methods to be
9078 <internallink id="bci">instrumented</internallink>.
9079 <p/>
9080 Since native methods cannot be directly instrumented
9081 (they have no bytecodes), they must be wrapped with
9082 a non-native method which can be instrumented.
9083 For example, if we had:
9084 <example>
9085 native boolean foo(int x);</example>
9086 <p/>
9087 We could transform the class file (with the
9088 ClassFileLoadHook event) so that this becomes:
9089 <example>
9090 boolean foo(int x) {
9091 <i>... record entry to foo ...</i>
9092 return wrapped_foo(x);
9093 }
9094
9095 native boolean wrapped_foo(int x);</example>
9096 <p/>
9097 Where foo becomes a wrapper for the actual native method
9098 with the appended prefix "wrapped_". Note that
9099 "wrapped_" would be a poor choice of prefix since it
9100 might conceivably form the name of an existing method
9101 thus something like "$$$MyAgentWrapped$$$_" would be
9102 better but would make these examples less readable.
9103 <p/>
9104 The wrapper will allow data to be collected on the native
9105 method call, but now the problem becomes linking up the
9106 wrapped method with the native implementation.
9107 That is, the method <code>wrapped_foo</code> needs to be
9108 resolved to the native implementation of <code>foo</code>,
9109 which might be:
9110 <example>
9111 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
9112 <p/>
9113 This function allows the prefix to be specified and the
9114 proper resolution to occur.
9115 Specifically, when the standard resolution fails, the
9116 resolution is retried taking the prefix into consideration.
9117 There are two ways that resolution occurs, explicit
9118 resolution with the JNI function <code>RegisterNatives</code>
9119 and the normal automatic resolution. For
9120 <code>RegisterNatives</code>, the VM will attempt this
9121 association:
9122 <example>
9123 method(foo) -> nativeImplementation(foo)</example>
9124 <p/>
9125 When this fails, the resolution will be retried with
9126 the specified prefix prepended to the method name,
9127 yielding the correct resolution:
9128 <example>
9129 method(wrapped_foo) -> nativeImplementation(foo)</example>
9130 <p/>
9131 For automatic resolution, the VM will attempt:
9132 <example>
9133 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
9134 <p/>
9135 When this fails, the resolution will be retried with
9136 the specified prefix deleted from the implementation name,
9137 yielding the correct resolution:
9138 <example>
9139 method(wrapped_foo) -> nativeImplementation(foo)</example>
9140 <p/>
9141 Note that since the prefix is only used when standard
9142 resolution fails, native methods can be wrapped selectively.
9143 <p/>
9144 Since each <jvmti/> environment is independent and
9145 can do its own transformation of the bytecodes, more
9146 than one layer of wrappers may be applied. Thus each
9147 environment needs its own prefix. Since transformations
9148 are applied in order, the prefixes, if applied, will
9149 be applied in the same order.
9150 The order of transformation application is described in
9151 the <eventlink id="ClassFileLoadHook"/> event.
9152 Thus if three environments applied
9153 wrappers, <code>foo</code> might become
9154 <code>$env3_$env2_$env1_foo</code>. But if, say,
9155 the second environment did not apply a wrapper to
9156 <code>foo</code> it would be just
9157 <code>$env3_$env1_foo</code>. To be able to
9158 efficiently determine the sequence of prefixes,
9159 an intermediate prefix is only applied if its non-native
9160 wrapper exists. Thus, in the last example, even though
9161 <code>$env1_foo</code> is not a native method, the
9162 <code>$env1_</code> prefix is applied since
9163 <code>$env1_foo</code> exists.
9164 <p/>
9165 Since the prefixes are used at resolution time
9166 and since resolution may be arbitrarily delayed, a
9167 native method prefix must remain set as long as there
9168 are corresponding prefixed native methods.
9169 </description>
9170 <origin>new</origin>
9171 <capabilities>
9172 <required id="can_set_native_method_prefix"></required>
9173 </capabilities>
9174 <parameters>
9175 <param id="prefix">
9176 <inbuf>
9177 <char/>
9178 <nullok>
9179 any existing prefix in this environment is cancelled
9180 </nullok>
9181 </inbuf>
9182 <description>
9183 The prefix to apply, encoded as a
9184 <internallink id="mUTF">modified UTF-8</internallink> string.
9185 </description>
9186 </param>
9187 </parameters>
9188 <errors>
9189 </errors>
9190 </function>
9191
9192 <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
9193 <synopsis>Set Native Method Prefixes</synopsis>
9194 <description>
9195 For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
9196 will provide all needed native method prefixing.
9197 For a meta-agent that performs multiple independent class
9198 file transformations (for example as a proxy for another
9199 layer of agents) this function allows each transformation
9200 to have its own prefix.
9201 The prefixes are applied in the order supplied and are
9202 processed in the same manner as described for the
9203 application of prefixes from multiple <jvmti/> environments
9204 in <functionlink id="SetNativeMethodPrefix"/>.
9205 <p/>
9206 Any previous prefixes are replaced. Thus, calling this
9207 function with a <paramlink id="prefix_count"/> of <code>0</code>
9208 disables prefixing in this environment.
9209 <p/>
9210 <functionlink id="SetNativeMethodPrefix"/> and this function
9211 are the two ways to set the prefixes.
9212 Calling <code>SetNativeMethodPrefix</code> with
9213 a prefix is the same as calling this function with
9214 <paramlink id="prefix_count"/> of <code>1</code>.
9215 Calling <code>SetNativeMethodPrefix</code> with
9216 <code>NULL</code> is the same as calling this function with
9217 <paramlink id="prefix_count"/> of <code>0</code>.
9218 </description>
9219 <origin>new</origin>
9220 <capabilities>
9221 <required id="can_set_native_method_prefix"></required>
9222 </capabilities>
9223 <parameters>
9224 <param id="prefix_count">
9225 <jint min="0"/>
9226 <description>
9227 The number of prefixes to apply.
9228 </description>
9229 </param>
9230 <param id="prefixes">
9231 <agentbuf>
9232 <char/>
9233 </agentbuf>
9234 <description>
9235 The prefixes to apply for this environment, each encoded as a
9236 <internallink id="mUTF">modified UTF-8</internallink> string.
9237 </description>
9238 </param>
9239 </parameters>
9240 <errors>
9241 </errors>
9242 </function>
9243
9244 </category>
9245
9246 <category id="RawMonitors" label="Raw Monitor">
9247
9248 <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
9249 <synopsis>Create Raw Monitor</synopsis>
9250 <description>
9251 Create a raw monitor.
9252 </description>
9253 <origin>jvmdi</origin>
9254 <capabilities>
9255 </capabilities>
9256 <parameters>
9257 <param id="name">
9258 <inbuf><char/></inbuf>
9259 <description>
9260 A name to identify the monitor, encoded as a
9261 <internallink id="mUTF">modified UTF-8</internallink> string.
9262 </description>
9263 </param>
9264 <param id="monitor_ptr">
9265 <outptr><jrawMonitorID/></outptr>
9266 <description>
9267 On return, points to the created monitor.
9268 </description>
9269 </param>
9270 </parameters>
9271 <errors>
9272 </errors>
9273 </function>
9274
9275 <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
9276 <synopsis>Destroy Raw Monitor</synopsis>
9277 <description>
9278 Destroy the raw monitor.
9279 If the monitor being destroyed has been entered by this thread, it will be
9280 exited before it is destroyed.
9281 If the monitor being destroyed has been entered by another thread,
9282 an error will be returned and the monitor will not be destroyed.
9283 </description>
9284 <origin>jvmdi</origin>
9285 <capabilities>
9286 </capabilities>
9287 <parameters>
9288 <param id="monitor">
9289 <jrawMonitorID/>
9290 <description>
9291 The monitor
9292 </description>
9293 </param>
9294 </parameters>
9295 <errors>
9296 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9297 Not monitor owner
9298 </error>
9299 </errors>
9300 </function>
9301
9302 <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
9303 <synopsis>Raw Monitor Enter</synopsis>
9304 <description>
9305 Gain exclusive ownership of a raw monitor.
9306 The same thread may enter a monitor more then once.
9307 The thread must
9308 <functionlink id="RawMonitorExit">exit</functionlink>
9309 the monitor the same number of times as it is entered.
9310 If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
9311 and has not exited when attached threads come into existence, the enter
9312 is considered to have occurred on the main thread.
9313 </description>
9314 <origin>jvmdi</origin>
9315 <capabilities>
9316 </capabilities>
9317 <parameters>
9318 <param id="monitor">
9319 <jrawMonitorID/>
9320 <description>
9321 The monitor
9322 </description>
9323 </param>
9324 </parameters>
9325 <errors>
9326 </errors>
9327 </function>
9328
9329 <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
9330 <synopsis>Raw Monitor Exit</synopsis>
9331 <description>
9332 Release exclusive ownership of a raw monitor.
9333 </description>
9334 <origin>jvmdi</origin>
9335 <capabilities>
9336 </capabilities>
9337 <parameters>
9338 <param id="monitor">
9339 <jrawMonitorID/>
9340 <description>
9341 The monitor
9342 </description>
9343 </param>
9344 </parameters>
9345 <errors>
9346 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9347 Not monitor owner
9348 </error>
9349 </errors>
9350 </function>
9351
9352 <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
9353 <synopsis>Raw Monitor Wait</synopsis>
9354 <description>
9355 Wait for notification of the raw monitor.
9356 <p/>
9357 Causes the current thread to wait until either another thread calls
9358 <functionlink id="RawMonitorNotify"/> or
9359 <functionlink id="RawMonitorNotifyAll"/>
9360 for the specified raw monitor, or the specified
9361 <paramlink id="millis">timeout</paramlink>
9362 has elapsed.
9363 </description>
9364 <origin>jvmdi</origin>
9365 <capabilities>
9366 </capabilities>
9367 <parameters>
9368 <param id="monitor">
9369 <jrawMonitorID/>
9370 <description>
9371 The monitor
9372 </description>
9373 </param>
9374 <param id="millis">
9375 <jlong/>
9376 <description>
9377 The timeout, in milliseconds. If the timeout is
9378 zero, then real time is not taken into consideration
9379 and the thread simply waits until notified.
9380 </description>
9381 </param>
9382 </parameters>
9383 <errors>
9384 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9385 Not monitor owner
9386 </error>
9387 <error id="JVMTI_ERROR_INTERRUPT">
9388 Wait was interrupted, try again
9389 </error>
9390 </errors>
9391 </function>
9392
9393 <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
9394 <synopsis>Raw Monitor Notify</synopsis>
9395 <description>
9396 Notify a single thread waiting on the raw monitor.
9397 </description>
9398 <origin>jvmdi</origin>
9399 <capabilities>
9400 </capabilities>
9401 <parameters>
9402 <param id="monitor">
9403 <jrawMonitorID/>
9404 <description>
9405 The monitor
9406 </description>
9407 </param>
9408 </parameters>
9409 <errors>
9410 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9411 Not monitor owner
9412 </error>
9413 </errors>
9414 </function>
9415
9416 <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
9417 <synopsis>Raw Monitor Notify All</synopsis>
9418 <description>
9419 Notify all threads waiting on the raw monitor.
9420 </description>
9421 <origin>jvmdi</origin>
9422 <capabilities>
9423 </capabilities>
9424 <parameters>
9425 <param id="monitor">
9426 <jrawMonitorID/>
9427 <description>
9428 The monitor
9429 </description>
9430 </param>
9431 </parameters>
9432 <errors>
9433 <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9434 Not monitor owner
9435 </error>
9436 </errors>
9437 </function>
9438
9439 <elide>
9440 <function id="GetRawMonitorUse" num="118">
9441 <synopsis>Get Raw Monitor Use</synopsis>
9442 <description>
9443 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
9444 are filled in with information about usage of the raw monitor.
9445 </description>
9446 <origin>new</origin>
9447 <capabilities>
9448 <required id="can_get_raw_monitor_usage"></required>
9449 </capabilities>
9450 <parameters>
9451 <param id="monitor">
9452 <jrawMonitorID/>
9453 <description>
9454 the raw monitor to query.
9455 </description>
9456 </param>
9457 <param id="info_ptr">
9458 <outptr><struct>jvmtiMonitorUsage</struct></outptr>
9459 <description>
9460 On return, filled with monitor information for the
9461 specified raw monitor.
9462 </description>
9463 </param>
9464 </parameters>
9465 <errors>
9466 </errors>
9467 </function>
9468
9469 <function id="GetRawMonitors" num="119">
9470 <synopsis>Get Raw Monitors</synopsis>
9471 <description>
9472 Return the list of raw monitors.
9473 <p/>
9474 Note: details about each monitor can be examined with
9475 <functionlink id="GetRawMonitorUse"></functionlink>.
9476 </description>
9477 <origin>new</origin>
9478 <capabilities>
9479 <required id="can_get_raw_monitor_usage"></required>
9480 </capabilities>
9481 <parameters>
9482 <param id="monitorCnt">
9483 <outptr><jint/></outptr>
9484 <description>
9485 On return, pointer to the number
9486 of monitors returned in <code>monitors_ptr</code>.
9487 </description>
9488 </param>
9489 <param id="monitors_ptr">
9490 <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
9491 <description>
9492 On return, pointer to the monitor list.
9493 </description>
9494 </param>
9495 </parameters>
9496 <errors>
9497 </errors>
9498 </function>
9499 </elide>
9500 </category>
9501
9502 <category id="jniIntercept" label="JNI Function Interception">
9503
9504 <intro>
9505 Provides the ability to intercept and resend
9506 Java Native Interface (JNI) function calls
9507 by manipulating the JNI function table.
9508 See <externallink id="jni/functions.html">JNI
9509 Functions</externallink> in the <i>Java Native Interface Specification</i>.
9510 <p/>
9511 The following example illustrates intercepting the
9512 <code>NewGlobalRef</code> JNI call in order to count reference
9513 creation.
9514 <example>
9515 JNIEnv original_jni_Functions;
9516 JNIEnv redirected_jni_Functions;
9517 int my_global_ref_count = 0;
9518
9519 jobject
9520 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
9521 ++my_global_ref_count;
9522 return originalJNIFunctions->NewGlobalRef(env, lobj);
9523 }
9524
9525 void
9526 myInit() {
9527 jvmtiError err;
9528
9529 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions);
9530 if (err != JVMTI_ERROR_NONE) {
9531 die();
9532 }
9533 err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions);
9534 if (err != JVMTI_ERROR_NONE) {
9535 die();
9536 }
9537 redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef;
9538 err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
9539 if (err != JVMTI_ERROR_NONE) {
9540 die();
9541 }
9542 }
9543 </example>
9544 Sometime after <code>myInit</code> is called the user's JNI
9545 code is executed which makes the call to create a new global
9546 reference. Instead of going to the normal JNI implementation
9547 the call goes to <code>myNewGlobalRef</code>. Note that a
9548 copy of the original function table is kept so that the normal
9549 JNI function can be called after the data is collected.
9550 Note also that any JNI functions which are not overwritten
9551 will behave normally.
9552 <todo>
9553 check that the example compiles and executes.
9554 </todo>
9555 </intro>
9556
9557 <function id="SetJNIFunctionTable" phase="start" num="120">
9558 <synopsis>Set JNI Function Table</synopsis>
9559 <description>
9560 Set the JNI function table
9561 in all current and future JNI environments.
9562 As a result, all future JNI calls are directed to the specified functions.
9563 Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
9564 function table to pass to this function.
9565 For this function to take effect the updated table entries must be
9566 used by the JNI clients.
9567 Since the table is defined <code>const</code> some compilers may optimize
9568 away the access to the table, thus preventing this function from taking
9569 effect.
9570 The table is copied--changes to the local copy of the
9571 table have no effect.
9572 This function affects only the function table, all other aspects of the environment are
9573 unaffected.
9574 See the examples <internallink id="jniIntercept">above</internallink>.
9575 </description>
9576 <origin>new</origin>
9577 <capabilities>
9578 </capabilities>
9579 <parameters>
9580 <param id="function_table">
9581 <inptr>
9582 <struct>jniNativeInterface</struct>
9583 </inptr>
9584 <description>
9585 Points to the new JNI function table.
9586 </description>
9587 </param>
9588 </parameters>
9589 <errors>
9590 </errors>
9591 </function>
9592
9593 <function id="GetJNIFunctionTable" phase="start" num="121">
9594 <synopsis>Get JNI Function Table</synopsis>
9595 <description>
9596 Get the JNI function table.
9597 The JNI function table is copied into allocated memory.
9598 If <functionlink id="SetJNIFunctionTable"></functionlink>
9599 has been called, the modified (not the original) function
9600 table is returned.
9601 Only the function table is copied, no other aspects of the environment
9602 are copied.
9603 See the examples <internallink id="jniIntercept">above</internallink>.
9604 </description>
9605 <origin>new</origin>
9606 <capabilities>
9607 </capabilities>
9608 <parameters>
9609 <param id="function_table">
9610 <allocbuf>
9611 <struct>jniNativeInterface</struct>
9612 </allocbuf>
9613 <description>
9614 On return, <code>*function_table</code>
9615 points a newly allocated copy of the JNI function table.
9616 </description>
9617 </param>
9618 </parameters>
9619 <errors>
9620 </errors>
9621 </function>
9622
9623 </category>
9624
9625 <category id="eventManagement" label="Event Management">
9626
9627 <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
9628 <synopsis>Set Event Callbacks</synopsis>
9629 <description>
9630 Set the functions to be called for each event.
9631 The callbacks are specified by supplying a replacement function table.
9632 The function table is copied--changes to the local copy of the
9633 table have no effect.
9634 This is an atomic action, all callbacks are set at once.
9635 No events are sent before this function is called.
9636 When an entry is <code>NULL</code> or when the event is beyond
9637 <paramlink id="size_of_callbacks"></paramlink> no event is sent.
9638 Details on events are
9639 described <internallink id="EventSection">later</internallink> in this document.
9640 An event must be enabled and have a callback in order to be
9641 sent--the order in which this function and
9642 <functionlink id="SetEventNotificationMode"></functionlink>
9643 are called does not affect the result.
9644 </description>
9645 <origin>new</origin>
9646 <capabilities>
9647 </capabilities>
9648 <parameters>
9649 <param id="callbacks">
9650 <inptr>
9651 <struct>jvmtiEventCallbacks</struct>
9652 <nullok>remove the existing callbacks</nullok>
9653 </inptr>
9654 <description>
9655 The new event callbacks.
9656 </description>
9657 </param>
9658 <param id="size_of_callbacks">
9659 <jint min="0"/>
9660 <description>
9661 <code>sizeof(jvmtiEventCallbacks)</code>--for version
9662 compatibility.
9663 </description>
9664 </param>
9665 </parameters>
9666 <errors>
9667 </errors>
9668 </function>
9669
9670 <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
9671 <synopsis>Set Event Notification Mode</synopsis>
9672 <description>
9673 Control the generation of events.
9674 <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
9675 <constant id="JVMTI_ENABLE" num="1">
9676 If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>,
9677 the event <paramlink id="event_type"></paramlink> will be enabled
9678 </constant>
9679 <constant id="JVMTI_DISABLE" num="0">
9680 If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>,
9681 the event <paramlink id="event_type"></paramlink> will be disabled
9682 </constant>
9683 </constants>
9684 If <code>event_thread</code> is <code>NULL</code>,
9685 the event is enabled or disabled globally; otherwise, it is
9686 enabled or disabled for a particular thread.
9687 An event is generated for
9688 a particular thread if it is enabled either at the thread or global
9689 levels.
9690 <p/>
9691 See <internallink id="EventIndex">below</internallink> for information on specific events.
9692 <p/>
9693 The following events cannot be controlled at the thread
9694 level through this function.
9695 <ul>
9696 <li><eventlink id="VMInit"></eventlink></li>
9697 <li><eventlink id="VMStart"></eventlink></li>
9698 <li><eventlink id="VMDeath"></eventlink></li>
9699 <li><eventlink id="ThreadStart"></eventlink></li>
9700 <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9701 <li><eventlink id="CompiledMethodUnload"></eventlink></li>
9702 <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9703 <li><eventlink id="DataDumpRequest"></eventlink></li>
9704 </ul>
9705 <p/>
9706 Initially, no events are enabled at either the thread level
9707 or the global level.
9708 <p/>
9709 Any needed capabilities (see Event Enabling Capabilities below) must be possessed
9710 before calling this function.
9711 <p/>
9712 Details on events are
9713 described <internallink id="EventSection">below</internallink>.
9714 </description>
9715 <origin>jvmdiClone</origin>
9716 <eventcapabilities></eventcapabilities>
9717 <parameters>
9718 <param id="mode">
9719 <enum>jvmtiEventMode</enum>
9720 <description>
9721 <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
9722 </description>
9723 </param>
9724 <param id="event_type">
9725 <enum>jvmtiEvent</enum>
9726 <description>
9727 the event to control
9728 </description>
9729 </param>
9730 <param id="event_thread">
9731 <ptrtype>
9732 <jthread impl="noconvert"/>
9733 <nullok>event is controlled at the global level</nullok>
9734 </ptrtype>
9735 <description>
9736 The thread to control
9737 </description>
9738 </param>
9739 <param id="...">
9740 <varargs/>
9741 <description>
9742 for future expansion
9743 </description>
9744 </param>
9745 </parameters>
9746 <errors>
9747 <error id="JVMTI_ERROR_INVALID_THREAD">
9748 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9749 </error>
9750 <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9751 <paramlink id="event_thread"/> is non-<code>NULL</code> and is not alive
9752 (has not been started or has terminated).
9753 </error>
9754 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9755 thread level control was attempted on events which do not
9756 permit thread level control.
9757 </error>
9758 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
9759 The Required Event Enabling Capability is not possessed.
9760 </error>
9761 </errors>
9762 </function>
9763
9764 <function id="GenerateEvents" num="123">
9765 <synopsis>Generate Events</synopsis>
9766 <description>
9767 Generate events to represent the current state of the VM.
9768 For example, if <paramlink id="event_type"/> is
9769 <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9770 a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9771 sent for each currently compiled method.
9772 Methods that were loaded and now have been unloaded are not sent.
9773 The history of what events have previously been sent does not
9774 effect what events are sent by this function--for example,
9775 all currently compiled methods
9776 will be sent each time this function is called.
9777 <p/>
9778 This function is useful when
9779 events may have been missed due to the agent attaching after program
9780 execution begins; this function generates the missed events.
9781 <p/>
9782 Attempts to execute Java programming language code or
9783 JNI functions may be paused until this function returns -
9784 so neither should be called from the thread sending the event.
9785 This function returns only after the missed events have been
9786 sent, processed and have returned.
9787 The event may be sent on a different thread than the thread
9788 on which the event occurred.
9789 The callback for the event must be set with
9790 <functionlink id="SetEventCallbacks"></functionlink>
9791 and the event must be enabled with
9792 <functionlink id="SetEventNotificationMode"></functionlink>
9793 or the events will not occur.
9794 If the VM no longer has the information to generate some or
9795 all of the requested events, the events are simply not sent -
9796 no error is returned.
9797 <p/>
9798 Only the following events are supported:
9799 <ul>
9800 <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9801 <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9802 </ul>
9803 </description>
9804 <origin>new</origin>
9805 <capabilities>
9806 <capability id="can_generate_compiled_method_load_events"></capability>
9807 </capabilities>
9808 <parameters>
9809 <param id="event_type">
9810 <enum>jvmtiEvent</enum>
9811 <description>
9812 The type of event to generate. Must be one of these:
9813 <ul>
9814 <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9815 <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9816 </ul>
9817 </description>
9818 </param>
9819 </parameters>
9820 <errors>
9821 <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
9822 <paramlink id="event_type"/> is
9823 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9824 and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9825 is <code>false</code>.
9826 </error>
9827 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9828 <paramlink id="event_type"/> is other than
9829 <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9830 or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9831 </error>
9832 </errors>
9833 </function>
9834
9835 </category>
9836
9837 <category id="extension" label="Extension Mechanism">
9838
9839 <intro>
9840 These functions
9841 allow a <jvmti/> implementation to provide functions and events
9842 beyond those defined in this specification.
9843 <p/>
9844 Both extension functions and extension events have parameters
9845 each of which has a 'type' and 'kind' chosen from the following tables:
9846
9847 <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9848 <constant id="JVMTI_TYPE_JBYTE" num="101">
9849 Java programming language primitive type - <code>byte</code>.
9850 JNI type <code>jbyte</code>.
9851 </constant>
9852 <constant id="JVMTI_TYPE_JCHAR" num="102">
9853 Java programming language primitive type - <code>char</code>.
9854 JNI type <code>jchar</code>.
9855 </constant>
9856 <constant id="JVMTI_TYPE_JSHORT" num="103">
9857 Java programming language primitive type - <code>short</code>.
9858 JNI type <code>jshort</code>.
9859 </constant>
9860 <constant id="JVMTI_TYPE_JINT" num="104">
9861 Java programming language primitive type - <code>int</code>.
9862 JNI type <datalink id="jint"></datalink>.
9863 </constant>
9864 <constant id="JVMTI_TYPE_JLONG" num="105">
9865 Java programming language primitive type - <code>long</code>.
9866 JNI type <datalink id="jlong"></datalink>.
9867 </constant>
9868 <constant id="JVMTI_TYPE_JFLOAT" num="106">
9869 Java programming language primitive type - <code>float</code>.
9870 JNI type <datalink id="jfloat"></datalink>.
9871 </constant>
9872 <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9873 Java programming language primitive type - <code>double</code>.
9874 JNI type <datalink id="jdouble"></datalink>.
9875 </constant>
9876 <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9877 Java programming language primitive type - <code>boolean</code>.
9878 JNI type <datalink id="jboolean"></datalink>.
9879 </constant>
9880 <constant id="JVMTI_TYPE_JOBJECT" num="109">
9881 Java programming language object type - <code>java.lang.Object</code>.
9882 JNI type <datalink id="jobject"></datalink>.
9883 Returned values are JNI local references and must be managed.
9884 </constant>
9885 <constant id="JVMTI_TYPE_JTHREAD" num="110">
9886 Java programming language object type - <code>java.lang.Thread</code>.
9887 <jvmti/> type <datalink id="jthread"></datalink>.
9888 Returned values are JNI local references and must be managed.
9889 </constant>
9890 <constant id="JVMTI_TYPE_JCLASS" num="111">
9891 Java programming language object type - <code>java.lang.Class</code>.
9892 JNI type <datalink id="jclass"></datalink>.
9893 Returned values are JNI local references and must be managed.
9894 </constant>
9895 <constant id="JVMTI_TYPE_JVALUE" num="112">
9896 Union of all Java programming language primitive and object types -
9897 JNI type <datalink id="jvalue"></datalink>.
9898 Returned values which represent object types are JNI local references and must be managed.
9899 </constant>
9900 <constant id="JVMTI_TYPE_JFIELDID" num="113">
9901 Java programming language field identifier -
9902 JNI type <datalink id="jfieldID"></datalink>.
9903 </constant>
9904 <constant id="JVMTI_TYPE_JMETHODID" num="114">
9905 Java programming language method identifier -
9906 JNI type <datalink id="jmethodID"></datalink>.
9907 </constant>
9908 <constant id="JVMTI_TYPE_CCHAR" num="115">
9909 C programming language type - <code>char</code>.
9910 </constant>
9911 <constant id="JVMTI_TYPE_CVOID" num="116">
9912 C programming language type - <code>void</code>.
9913 </constant>
9914 <constant id="JVMTI_TYPE_JNIENV" num="117">
9915 JNI environment - <code>JNIEnv</code>.
9916 Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9917 </constant>
9918 </constants>
9919
9920 <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9921 <constant id="JVMTI_KIND_IN" num="91">
9922 Ingoing argument - <code>foo</code>.
9923 </constant>
9924 <constant id="JVMTI_KIND_IN_PTR" num="92">
9925 Ingoing pointer argument - <code>const foo*</code>.
9926 </constant>
9927 <constant id="JVMTI_KIND_IN_BUF" num="93">
9928 Ingoing array argument - <code>const foo*</code>.
9929 </constant>
9930 <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9931 Outgoing allocated array argument - <code>foo**</code>.
9932 Free with <code>Deallocate</code>.
9933 </constant>
9934 <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9935 Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9936 Free with <code>Deallocate</code>.
9937 </constant>
9938 <constant id="JVMTI_KIND_OUT" num="96">
9939 Outgoing argument - <code>foo*</code>.
9940 </constant>
9941 <constant id="JVMTI_KIND_OUT_BUF" num="97">
9942 Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9943 Do not <code>Deallocate</code>.
9944 </constant>
9945 </constants>
9946
9947 </intro>
9948
9949 <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9950 <field id="name">
9951 <allocfieldbuf><char/></allocfieldbuf>
9952 <description>
9953 The parameter name, encoded as a
9954 <internallink id="mUTF">modified UTF-8</internallink> string
9955 </description>
9956 </field>
9957 <field id="kind">
9958 <enum>jvmtiParamKind</enum>
9959 <description>
9960 The kind of the parameter - type modifiers
9961 </description>
9962 </field>
9963 <field id="base_type">
9964 <enum>jvmtiParamTypes</enum>
9965 <description>
9966 The base type of the parameter - modified by <code>kind</code>
9967 </description>
9968 </field>
9969 <field id="null_ok">
9970 <jboolean/>
9971 <description>
9972 Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9973 </description>
9974 </field>
9975 </typedef>
9976
9977 <callback id="jvmtiExtensionFunction">
9978 <enum>jvmtiError</enum>
9979 <synopsis>Extension Function</synopsis>
9980 <description>
9981 This is the implementation-specific extension function.
9982 </description>
9983 <parameters>
9984 <param id="jvmti_env">
9985 <outptr>
9986 <struct>jvmtiEnv</struct>
9987 </outptr>
9988 <description>
9989 The <jvmti/> environment is the only fixed parameter for extension functions.
9990 </description>
9991 </param>
9992 <param id="...">
9993 <varargs/>
9994 <description>
9995 The extension function-specific parameters
9996 </description>
9997 </param>
9998 </parameters>
9999 </callback>
10000
10001 <function id="GetExtensionFunctions" phase="onload" num="124">
10002 <synopsis>Get Extension Functions</synopsis>
10003
10004 <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
10005 <field id="func">
10006 <ptrtype>
10007 <struct>jvmtiExtensionFunction</struct>
10008 </ptrtype>
10009 <description>
10010 The actual function to call
10011 </description>
10012 </field>
10013 <field id="id">
10014 <allocfieldbuf><char/></allocfieldbuf>
10015 <description>
10016 The identifier for the extension function, encoded as a
10017 <internallink id="mUTF">modified UTF-8</internallink> string.
10018 Uses package name conventions.
10019 For example, <code>com.sun.hotspot.bar</code>
10020 </description>
10021 </field>
10022 <field id="short_description">
10023 <allocfieldbuf><char/></allocfieldbuf>
10024 <description>
10025 A one sentence description of the function, encoded as a
10026 <internallink id="mUTF">modified UTF-8</internallink> string.
10027 </description>
10028 </field>
10029 <field id="param_count">
10030 <jint/>
10031 <description>
10032 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
10033 </description>
10034 </field>
10035 <field id="params">
10036 <allocfieldbuf outcount="param_count">
10037 <struct>jvmtiParamInfo</struct>
10038 </allocfieldbuf>
10039 <description>
10040 Array of
10041 <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
10042 parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
10043 </description>
10044 </field>
10045 <field id="error_count">
10046 <jint/>
10047 <description>
10048 The number of possible error returns (excluding universal errors)
10049 </description>
10050 </field>
10051 <field id="errors">
10052 <allocfieldbuf outcount="error_count">
10053 <enum>jvmtiError</enum>
10054 </allocfieldbuf>
10055 <description>
10056 Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
10057 possible errors
10058 </description>
10059 </field>
10060 </typedef>
10061
10062 <description>
10063 Returns the set of extension functions.
10064 </description>
10065 <origin>new</origin>
10066 <capabilities>
10067 </capabilities>
10068 <parameters>
10069 <param id="extension_count_ptr">
10070 <outptr><jint/></outptr>
10071 <description>
10072 On return, points to the number of extension functions
10073 </description>
10074 </param>
10075 <param id="extensions">
10076 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
10077 <description>
10078 Returns an array of extension function info, one per function
10079 </description>
10080 </param>
10081 </parameters>
10082 <errors>
10083 </errors>
10084 </function>
10085
10086 <function id="GetExtensionEvents" phase="onload" num="125">
10087 <synopsis>Get Extension Events</synopsis>
10088
10089 <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
10090 <field id="extension_event_index">
10091 <jint/>
10092 <description>
10093 The identifying index of the event
10094 </description>
10095 </field>
10096 <field id="id">
10097 <allocfieldbuf><char/></allocfieldbuf>
10098 <description>
10099 The identifier for the extension event, encoded as a
10100 <internallink id="mUTF">modified UTF-8</internallink> string.
10101 Uses package name conventions.
10102 For example, <code>com.sun.hotspot.bar</code>
10103 </description>
10104 </field>
10105 <field id="short_description">
10106 <allocfieldbuf><char/></allocfieldbuf>
10107 <description>
10108 A one sentence description of the event, encoded as a
10109 <internallink id="mUTF">modified UTF-8</internallink> string.
10110 </description>
10111 </field>
10112 <field id="param_count">
10113 <jint/>
10114 <description>
10115 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
10116 </description>
10117 </field>
10118 <field id="params">
10119 <allocfieldbuf outcount="param_count">
10120 <struct>jvmtiParamInfo</struct>
10121 </allocfieldbuf>
10122 <description>
10123 Array of
10124 <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
10125 parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
10126 </description>
10127 </field>
10128 </typedef>
10129
10130 <description>
10131 Returns the set of extension events.
10132 </description>
10133 <origin>new</origin>
10134 <capabilities>
10135 </capabilities>
10136 <parameters>
10137 <param id="extension_count_ptr">
10138 <outptr><jint/></outptr>
10139 <description>
10140 On return, points to the number of extension events
10141 </description>
10142 </param>
10143 <param id="extensions">
10144 <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
10145 <description>
10146 Returns an array of extension event info, one per event
10147 </description>
10148 </param>
10149 </parameters>
10150 <errors>
10151 </errors>
10152 </function>
10153
10154 <callback id="jvmtiExtensionEvent">
10155 <void/>
10156 <synopsis>Extension Event</synopsis>
10157 <description>
10158 This is the implementation-specific event.
10159 The event handler is set with
10160 <functionlink id="SetExtensionEventCallback"/>.
10161 <p/>
10162 Event handlers for extension events must be declared varargs to match this definition.
10163 Failure to do so could result in calling convention mismatch and undefined behavior
10164 on some platforms.
10165 <p/>
10166 For example, if the <code>jvmtiParamInfo</code>
10167 returned by <functionlink id="GetExtensionEvents"/> indicates that
10168 there is a <code>jint</code> parameter, the event handler should be
10169 declared:
10170 <example>
10171 void JNICALL myHandler(jvmtiEnv* jvmti_env, ...)
10172 </example>
10173 Note the terminal "<code>...</code>" which indicates varargs.
10174 The <code>jint</code> argument inside <code>myHandler</code> needs to be extracted using
10175 the <code>va_*</code> syntax of the C programming language.
10176 </description>
10177 <parameters>
10178 <param id="jvmti_env">
10179 <outptr>
10180 <struct>jvmtiEnv</struct>
10181 </outptr>
10182 <description>
10183 The <jvmti/> environment is the only fixed parameter for extension events.
10184 </description>
10185 </param>
10186 <param id="...">
10187 <varargs/>
10188 <description>
10189 The extension event-specific parameters
10190 </description>
10191 </param>
10192 </parameters>
10193 </callback>
10194
10195 <function id="SetExtensionEventCallback" phase="onload" num="126">
10196 <synopsis>Set Extension Event Callback</synopsis>
10197
10198 <description>
10199 Sets the callback function for an extension event and
10200 enables the event. Or, if the callback is <code>NULL</code>, disables
10201 the event. Note that unlike standard events, setting
10202 the callback and enabling the event are a single operation.
10203 </description>
10204 <origin>new</origin>
10205 <capabilities>
10206 </capabilities>
10207 <parameters>
10208 <param id="extension_event_index">
10209 <jint/>
10210 <description>
10211 Identifies which callback to set.
10212 This index is the
10213 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
10214 field of
10215 <datalink id="jvmtiExtensionEventInfo"/>.
10216 </description>
10217 </param>
10218 <param id="callback">
10219 <ptrtype>
10220 <struct>jvmtiExtensionEvent</struct>
10221 <nullok>disable the event</nullok>
10222 </ptrtype>
10223 <description>
10224 If <code>callback</code> is non-<code>NULL</code>,
10225 set <code>callback</code> to be the event callback function
10226 and enable the event.
10227 </description>
10228 </param>
10229 </parameters>
10230 <errors>
10231 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10232 <paramlink id="extension_event_index"/> is not an
10233 <fieldlink id="extension_event_index"
10234 struct="jvmtiExtensionEventInfo"/>
10235 returned by
10236 <functionlink id="GetExtensionEvents"/>
10237 </error>
10238 </errors>
10239 </function>
10240
10241 </category>
10242
10243 <category id="capability" label="Capability">
10244
10245 <intro>
10246 The capabilities functions allow you to change the
10247 functionality available to <jvmti/>--that is,
10248 which <jvmti/>
10249 functions can be called, what events can be generated,
10250 and what functionality these events and functions can
10251 provide.
10252 <p/>
10253 The "Capabilities" section of each function and event describe which
10254 capabilities, if any, they are associated with. "Required Functionality"
10255 means it is available for use and no capabilities must be added to use it.
10256 "Optional Functionality" means the agent must possess the capability
10257 before it can be used.
10258 To possess a capability, the agent must
10259 <functionlink id="AddCapabilities">add the capability</functionlink>.
10260 "Optional Features" describe capabilities which,
10261 if added, extend the feature set.
10262 <p/>
10263 The potentially available capabilities of each <jvmti/> implementation are different.
10264 Depending on the implementation, a capability:
10265 <ul>
10266 <li>may never be added</li>
10267 <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
10268 <li>may be added only during the <code>OnLoad</code> phase</li>
10269 <li>may be possessed by only one environment at a time</li>
10270 <li>may be possessed by only one environment at a time,
10271 and only during the <code>OnLoad</code> phase</li>
10272 <li>and so on ...</li>
10273 </ul>
10274 Frequently, the addition of a capability may incur a cost in execution speed, start up
10275 time, and/or memory footprint. Note that the overhead of using a capability
10276 is completely different than the overhead of possessing a capability.
10277 Take single stepping as an example. When single stepping is on (that
10278 is, when the event is enabled and thus actively sending events)
10279 the overhead of sending and processing an event
10280 on each instruction is huge in any implementation.
10281 However, the overhead of possessing the capability may be small or large,
10282 depending on the implementation. Also, when and if a capability is potentially
10283 available depends on the implementation. Some examples:
10284 <ul>
10285 <li>One VM might perform all execution by compiling bytecodes into
10286 native code and be unable to generate single step instructions.
10287 In this implementation the capability can not be added.</li>
10288 <li>Another VM may be able to switch execution to a single stepping
10289 interpreter at any time. In this implementation, having the capability has no
10290 overhead and could be added at any time.</li>
10291 <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
10292 execution engine at start up, but be unable to switch between them.
10293 In this implementation the capability would need to be added
10294 during the <code>OnLoad</code> phase (before bytecode
10295 execution begins) and would have a large impact on execution speed
10296 even if single stepping was never used.</li>
10297 <li>Still another VM might be able to add an "is single stepping on" check
10298 into compiled bytecodes or a generated interpreter. Again in this implementation
10299 the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
10300 and branch on each instruction) would be considerably less.</li>
10301 </ul>
10302 <p/>
10303 Each <jvmti/> <internallink id="environments">environment</internallink>
10304 has its own set of capabilities.
10305 Initially, that set is empty.
10306 Any desired capability must be added.
10307 If possible, capabilities should be added during the <code>OnLoad</code> phase. For most
10308 virtual machines certain capabilities require special set up for
10309 the virtual machine and this set up must happen
10310 during the <code>OnLoad</code> phase, before the virtual machine begins execution.
10311 Once a capability is added, it can
10312 only be removed if explicitly relinquished by the environment.
10313 <p/>
10314 The agent can,
10315 <functionlink id="GetPotentialCapabilities">determine what
10316 capabilities this VM can potentially provide</functionlink>,
10317 <functionlink id="AddCapabilities">add the capabilities
10318 to be used</functionlink>,
10319 <functionlink id="RelinquishCapabilities">release capabilities
10320 which are no longer needed</functionlink>, and
10321 <functionlink id="GetCapabilities">examine the currently available
10322 capabilities</functionlink>.
10323 </intro>
10324
10325 <intro id="capabilityExamples" label="Capability Examples">
10326 For example, a freshly started agent (in the <code>OnLoad</code> function)
10327 wants to enable all possible capabilities.
10328 Note that, in general, this is not advisable as the agent may suffer
10329 a performance penalty for functionality it is not using.
10330 The code might look like this in C:
10331 <example>
10332 jvmtiCapabilities capa;
10333 jvmtiError err;
10334
10335 err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa);
10336 if (err == JVMTI_ERROR_NONE) {
10337 err = (*jvmti)->AddCapabilities(jvmti, &capa);
10338 </example>
10339 For example, if an agent wants to check if it can get
10340 the bytecodes of a method (that is, it wants to check
10341 if it previously added this capability and has not
10342 relinquished it), the code might
10343 look like this in C:
10344 <example>
10345 jvmtiCapabilities capa;
10346 jvmtiError err;
10347
10348 err = (*jvmti)->GetCapabilities(jvmti, &capa);
10349 if (err == JVMTI_ERROR_NONE) {
10350 if (capa.can_get_bytecodes) { ... } }
10351 </example>
10352 </intro>
10353
10354 <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
10355 <description>
10356 The functions in this category use this capabilities structure
10357 which contains boolean flags corresponding to each capability:
10358 </description>
10359 <capabilityfield id="can_tag_objects">
10360 <description>
10361 Can set and get tags, as described in the
10362 <internallink id="Heap">Heap category</internallink>.
10363 </description>
10364 </capabilityfield>
10365 <capabilityfield id="can_generate_field_modification_events">
10366 <description>
10367 Can set watchpoints on field modification -
10368 <functionlink id="SetFieldModificationWatch"></functionlink>
10369 </description>
10370 </capabilityfield>
10371 <capabilityfield id="can_generate_field_access_events">
10372 <description>
10373 Can set watchpoints on field access -
10374 <functionlink id="SetFieldAccessWatch"></functionlink>
10375 </description>
10376 </capabilityfield>
10377 <capabilityfield id="can_get_bytecodes">
10378 <description>
10379 Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
10380 </description>
10381 </capabilityfield>
10382 <capabilityfield id="can_get_synthetic_attribute">
10383 <description>
10384 Can test if a field or method is synthetic -
10385 <functionlink id="IsFieldSynthetic"></functionlink> and
10386 <functionlink id="IsMethodSynthetic"></functionlink>
10387 </description>
10388 </capabilityfield>
10389 <capabilityfield id="can_get_owned_monitor_info">
10390 <description>
10391 Can get information about ownership of monitors -
10392 <functionlink id="GetOwnedMonitorInfo"></functionlink>
10393 </description>
10394 </capabilityfield>
10395 <capabilityfield id="can_get_current_contended_monitor">
10396 <description>
10397 Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
10398 </description>
10399 </capabilityfield>
10400 <capabilityfield id="can_get_monitor_info">
10401 <description>
10402 Can <functionlink id="GetObjectMonitorUsage"></functionlink>
10403 </description>
10404 </capabilityfield>
10405 <capabilityfield id="can_pop_frame">
10406 <description>
10407 Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
10408 </description>
10409 </capabilityfield>
10410 <capabilityfield id="can_redefine_classes">
10411 <description>
10412 Can redefine classes with <functionlink id="RedefineClasses"/>.
10413 </description>
10414 </capabilityfield>
10415 <capabilityfield id="can_signal_thread">
10416 <description>
10417 Can send stop or interrupt to threads
10418 </description>
10419 </capabilityfield>
10420 <capabilityfield id="can_get_source_file_name">
10421 <description>
10422 Can get the source file name of a class
10423 </description>
10424 </capabilityfield>
10425 <capabilityfield id="can_get_line_numbers">
10426 <description>
10427 Can get the line number table of a method
10428 </description>
10429 </capabilityfield>
10430 <capabilityfield id="can_get_source_debug_extension">
10431 <description>
10432 Can get the source debug extension of a class
10433 </description>
10434 </capabilityfield>
10435 <capabilityfield id="can_access_local_variables">
10436 <description>
10437 Can set and get local variables
10438 </description>
10439 </capabilityfield>
10440 <capabilityfield id="can_maintain_original_method_order">
10441 <description>
10442 Can return methods in the order they occur in the class file
10443 </description>
10444 </capabilityfield>
10445 <capabilityfield id="can_generate_single_step_events">
10446 <description>
10447 Can get <eventlink id="SingleStep">single step</eventlink> events
10448 </description>
10449 </capabilityfield>
10450 <capabilityfield id="can_generate_exception_events">
10451 <description>
10452 Can get <eventlink id="Exception">exception thrown</eventlink> and
10453 <eventlink id="ExceptionCatch">exception catch</eventlink> events
10454 </description>
10455 </capabilityfield>
10456 <capabilityfield id="can_generate_frame_pop_events">
10457 <description>
10458 Can <functionlink id="NotifyFramePop">set</functionlink> and thus get
10459 <eventlink id="FramePop"></eventlink> events
10460 </description>
10461 </capabilityfield>
10462 <capabilityfield id="can_generate_breakpoint_events">
10463 <description>
10464 Can <functionlink id="SetBreakpoint">set</functionlink> and thus get
10465 <eventlink id="Breakpoint"></eventlink> events
10466 </description>
10467 </capabilityfield>
10468 <capabilityfield id="can_suspend">
10469 <description>
10470 Can suspend and resume threads
10471 </description>
10472 </capabilityfield>
10473 <capabilityfield id="can_redefine_any_class">
10474 <description>
10475 <functionlink id="RedefineClasses"/> can be called on any modifiable class.
10476 See <functionlink id="IsModifiableClass"/>.
10477 (<fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
10478 must also be set)
10479 </description>
10480 </capabilityfield>
10481 <capabilityfield id="can_get_current_thread_cpu_time">
10482 <description>
10483 Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
10484 current thread CPU time
10485 </description>
10486 </capabilityfield>
10487 <capabilityfield id="can_get_thread_cpu_time">
10488 <description>
10489 Can <functionlink id="GetThreadCpuTime">get</functionlink>
10490 thread CPU time
10491 </description>
10492 </capabilityfield>
10493 <capabilityfield id="can_generate_method_entry_events"
10494 disp1="can_generate" disp2="_method_entry_events"
10495 >
10496 <description>
10497 Can generate method entry events on entering a method
10498 </description>
10499 </capabilityfield>
10500 <capabilityfield id="can_generate_method_exit_events"
10501 disp1="can_generate" disp2="_method_exit_events"
10502 >
10503 <description>
10504 Can generate method exit events on leaving a method
10505 </description>
10506 </capabilityfield>
10507 <capabilityfield id="can_generate_all_class_hook_events"
10508 disp1="can_generate" disp2="_all_class_hook_events"
10509 >
10510 <description>
10511 Can generate ClassFileLoadHook events for every loaded class.
10512 </description>
10513 </capabilityfield>
10514 <capabilityfield id="can_generate_compiled_method_load_events"
10515 disp1="can_generate" disp2="_compiled_method_load_events"
10516 >
10517 <description>
10518 Can generate events when a method is compiled or unloaded
10519 </description>
10520 </capabilityfield>
10521 <capabilityfield id="can_generate_monitor_events"
10522 disp1="can_generate" disp2="_monitor_events"
10523 >
10524 <description>
10525 Can generate events on monitor activity
10526 </description>
10527 </capabilityfield>
10528 <capabilityfield id="can_generate_vm_object_alloc_events"
10529 disp1="can_generate" disp2="_vm_object_alloc_events"
10530 >
10531 <description>
10532 Can generate events on VM allocation of an object
10533 </description>
10534 </capabilityfield>
10535 <capabilityfield id="can_generate_native_method_bind_events"
10536 disp1="can_generate" disp2="_native_method_bind_events"
10537 >
10538 <description>
10539 Can generate events when a native method is bound to its
10540 implementation
10541 </description>
10542 </capabilityfield>
10543 <capabilityfield id="can_generate_garbage_collection_events"
10544 disp1="can_generate" disp2="_garbage_collection_events"
10545 >
10546 <description>
10547 Can generate events when garbage collection begins or ends
10548 </description>
10549 </capabilityfield>
10550 <capabilityfield id="can_generate_object_free_events"
10551 disp1="can_generate" disp2="_object_free_events"
10552 >
10553 <description>
10554 Can generate events when the garbage collector frees an object
10555 </description>
10556 </capabilityfield>
10557 <capabilityfield id="can_force_early_return" since="1.1">
10558 <description>
10559 Can return early from a method, as described in the
10560 <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
10561 </description>
10562 </capabilityfield>
10563 <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
10564 <description>
10565 Can get information about owned monitors with stack depth -
10566 <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
10567 </description>
10568 </capabilityfield>
10569 <capabilityfield id="can_get_constant_pool" since="1.1">
10570 <description>
10571 Can get the constant pool of a class -
10572 <functionlink id="GetConstantPool"></functionlink>
10573 </description>
10574 </capabilityfield>
10575 <capabilityfield id="can_set_native_method_prefix" since="1.1">
10576 <description>
10577 Can set prefix to be applied when native method cannot be resolved -
10578 <functionlink id="SetNativeMethodPrefix"/> and
10579 <functionlink id="SetNativeMethodPrefixes"/>
10580 </description>
10581 </capabilityfield>
10582 <capabilityfield id="can_retransform_classes" since="1.1">
10583 <description>
10584 Can retransform classes with <functionlink id="RetransformClasses"/>.
10585 In addition to the restrictions imposed by the specific
10586 implementation on this capability (see the
10587 <internallink id="capability">Capability</internallink> section),
10588 this capability must be set before the
10589 <eventlink id="ClassFileLoadHook"/> event is enabled for the
10590 first time in this environment.
10591 An environment that possesses this capability at the time that
10592 <code>ClassFileLoadHook</code> is enabled for the first time is
10593 said to be <i>retransformation capable</i>.
10594 An environment that does not possess this capability at the time that
10595 <code>ClassFileLoadHook</code> is enabled for the first time is
10596 said to be <i>retransformation incapable</i>.
10597 </description>
10598 </capabilityfield>
10599 <capabilityfield id="can_retransform_any_class" since="1.1">
10600 <description>
10601 <functionlink id="RetransformClasses"/> can be called on any modifiable class.
10602 See <functionlink id="IsModifiableClass"/>.
10603 (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
10604 must also be set)
10605 </description>
10606 </capabilityfield>
10607 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
10608 <description>
10609 Can generate events when the VM is unable to allocate memory from
10610 the <tm>Java</tm> platform heap.
10611 See <eventlink id="ResourceExhausted"/>.
10612 </description>
10613 </capabilityfield>
10614 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
10615 <description>
10616 Can generate events when the VM is unable to create a thread.
10617 See <eventlink id="ResourceExhausted"/>.
10618 </description>
10619 </capabilityfield>
10620 <capabilityfield id="can_generate_early_vmstart" since="9">
10621 <description>
10622 Can generate the <code>VMStart</code> event early.
10623 See <eventlink id="VMStart"/>.
10624 </description>
10625 </capabilityfield>
10626 <capabilityfield id="can_generate_early_class_hook_events" since="9">
10627 <description>
10628 Can generate the <eventlink id="ClassFileLoadHook"/> events
10629 in the primordial phase. If this capability and
10630 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10631 <code>can_generate_all_class_hook_events</code></internallink>
10632 are enabled then the <eventlink id="ClassFileLoadHook"/> events
10633 can be posted for classes loaded in the primordial phase.
10634 See <eventlink id="ClassFileLoadHook"/>.
10635 </description>
10636 </capabilityfield>
10637 <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10638 <description>
10639 Can generate sampled allocation events.
10640 If this capability is enabled then the heap sampling method
10641 <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10642 called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10643 </description>
10644 </capabilityfield>
10645 <capabilityfield id="can_support_virtual_threads" since="21">
10646 <description>
10647 Can support virtual threads.
10648 If this capability is enabled then the following functions can be called:
10649 <functionlink id="SuspendAllVirtualThreads"></functionlink>,
10650 <functionlink id="ResumeAllVirtualThreads"></functionlink>,
10651 and the following events can be enabled:
10652 <eventlink id="VirtualThreadStart"></eventlink>,
10653 <eventlink id="VirtualThreadEnd"></eventlink>.
10654 </description>
10655 </capabilityfield>
10656 </capabilitiestypedef>
10657
10658 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10659 <synopsis>Get Potential Capabilities</synopsis>
10660 <description>
10661 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10662 features that can potentially be possessed by this environment
10663 at this time.
10664 The returned capabilities differ from the complete set of capabilities
10665 implemented by the VM in two cases: another environment possesses
10666 capabilities that can only be possessed by one environment, or the
10667 current <functionlink id="GetPhase">phase</functionlink> is live,
10668 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10669 The <functionlink id="AddCapabilities"></functionlink> function
10670 may be used to set any or all or these capabilities.
10671 Currently possessed capabilities are included.
10672 <p/>
10673 Typically this function is used in the <code>OnLoad</code> function.
10674 Some virtual machines may allow a limited set of capabilities to be
10675 added in the live phase.
10676 In this case, the set of potentially available capabilities
10677 will likely differ from the <code>OnLoad</code> phase set.
10678 <p/>
10679 See the
10680 <internallink id="capabilityExamples">Capability Examples</internallink>.
10681 </description>
10682 <origin>new</origin>
10683 <capabilities>
10684 </capabilities>
10685 <parameters>
10686 <param id="capabilities_ptr">
10687 <outptr><struct>jvmtiCapabilities</struct></outptr>
10688 <description>
10689 On return, points to the <jvmti/> capabilities that may be added.
10690 </description>
10691 </param>
10692 </parameters>
10693 <errors>
10694 </errors>
10695 </function>
10696
10697 <elide>
10698 <function id="EstimateCostOfCapabilities" phase="onload" num="141">
10699 <synopsis>Estimate Cost Of Capabilities</synopsis>
10700 <description>
10701 <issue>There is strong opposition to this function. The concern is
10702 that it would be difficult or impossible to provide meaningful
10703 numbers, as the amount of impact is conditional on many factors
10704 that a single number could not represent. There is doubt that
10705 conditional implementations would be used or are even a good idea.
10706 The thought is that release documentation for the implementation
10707 would be the best means of exposing this information.
10708 Unless new arguments are presented, I intend to remove this
10709 function in the next revision.
10710 </issue>
10711 <p/>
10712 Return via the <paramlink id="time_impact_ptr"></paramlink> and
10713 <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
10714 of adding the capabilities pointed to by
10715 <paramlink id="capabilities_ptr"></paramlink>.
10716 The returned estimates are in percentage of additional overhead, thus
10717 a time impact of 100 mean the application might run
10718 at half the speed.
10719 The estimates are very rough approximations and are not guaranteed.
10720 Note also, that the estimates are of the impact of having the
10721 capability available--when and if it is used the impact may be
10722 much greater.
10723 Estimates can be for a single capability or for a set of
10724 capabilities. Note that the costs are not necessarily additive,
10725 adding support for one capability might make another available
10726 for free or conversely having two capabilities at once may
10727 have multiplicative impact.
10728 Estimates are relative to the current set of capabilities -
10729 that is, how much more impact given the currently possessed capabilities.
10730 <p/>
10731 Typically this function is used in the OnLoad function,
10732 some virtual machines may allow a limited set of capabilities to be
10733 added in the live phase.
10734 In this case, the set of potentially available capabilities
10735 will likely differ from the OnLoad phase set.
10736 <p/>
10737 See the
10738 <internallink id="capabilityExamples">Capability Examples</internallink>.
10739 </description>
10740 <origin>new</origin>
10741 <capabilities>
10742 </capabilities>
10743 <parameters>
10744 <param id="capabilities_ptr">
10745 <inptr><struct>jvmtiCapabilities</struct></inptr>
10746 <description>
10747 points to the <jvmti/> capabilities to evaluate.
10748 </description>
10749 </param>
10750 <param id="time_impact_ptr">
10751 <outptr><jint/></outptr>
10752 <description>
10753 On return, points to the estimated percentage increase in
10754 run time if this capability was added.
10755 </description>
10756 </param>
10757 <param id="space_impact_ptr">
10758 <outptr><jint/></outptr>
10759 <description>
10760 On return, points to the estimated percentage increase in
10761 memory space used if this capability was added.
10762 </description>
10763 </param>
10764 </parameters>
10765 <errors>
10766 <error id="JVMTI_ERROR_NOT_AVAILABLE">
10767 The desired capabilities are not even potentially available.
10768 </error>
10769 </errors>
10770 </function>
10771 </elide>
10772
10773 <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10774 <synopsis>Add Capabilities</synopsis>
10775 <description>
10776 Set new capabilities by adding the capabilities
10777 whose values are set to one (<code>1</code>) in
10778 <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10779 All previous capabilities are retained.
10780 Typically this function is used in the <code>OnLoad</code> function.
10781 Some virtual machines may allow a limited set of capabilities to be
10782 added in the live phase.
10783 <p/>
10784 See the
10785 <internallink id="capabilityExamples">Capability Examples</internallink>.
10786 </description>
10787 <origin>new</origin>
10788 <capabilities>
10789 </capabilities>
10790 <parameters>
10791 <param id="capabilities_ptr">
10792 <inptr><struct>jvmtiCapabilities</struct></inptr>
10793 <description>
10794 Points to the <jvmti/> capabilities to add.
10795 </description>
10796 </param>
10797 </parameters>
10798 <errors>
10799 <error id="JVMTI_ERROR_NOT_AVAILABLE">
10800 The desired capabilities are not even potentially available.
10801 </error>
10802 </errors>
10803 </function>
10804
10805
10806 <function id="RelinquishCapabilities" phase="onload" num="143">
10807 <synopsis>Relinquish Capabilities</synopsis>
10808 <description>
10809 Relinquish the capabilities
10810 whose values are set to one (<code>1</code>) in
10811 <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10812 Some implementations may allow only one environment to have a capability
10813 (see the <internallink id="capability">capability introduction</internallink>).
10814 This function releases capabilities
10815 so that they may be used by other agents.
10816 All other capabilities are retained.
10817 The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10818 Attempting to relinquish a capability that the agent does not possess is not an error.
10819 <issue>
10820 It is possible for the agent to be actively using capabilities
10821 which are being relinquished. For example, a thread is currently
10822 suspended and can_suspend is being relinquished or an event is currently
10823 enabled and can_generate_whatever is being relinquished.
10824 There are three possible ways we could spec this:
10825 <ul>
10826 <li>relinquish automatically releases them</li>
10827 <li>relinquish checks and returns some error code if held</li>
10828 <li>it is the agent's responsibility and it is not checked</li>
10829 </ul>
10830 One of these should be chosen.
10831 </issue>
10832 </description>
10833 <origin>new</origin>
10834 <capabilities>
10835 </capabilities>
10836 <parameters>
10837 <param id="capabilities_ptr">
10838 <inptr><struct>jvmtiCapabilities</struct></inptr>
10839 <description>
10840 Points to the <jvmti/> capabilities to relinquish.
10841 </description>
10842 </param>
10843 </parameters>
10844 <errors>
10845 </errors>
10846 </function>
10847
10848
10849
10850 <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10851 <synopsis>Get Capabilities</synopsis>
10852 <description>
10853 Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/>
10854 features which this environment currently possesses.
10855 Each possessed capability is indicated by a one (<code>1</code>) in the
10856 corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10857 structure</internallink>.
10858 An environment does not possess a capability unless it has been successfully added with
10859 <functionlink id="AddCapabilities"/>.
10860 An environment only loses possession of a capability if it has been relinquished with
10861 <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10862 of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10863 have been made.
10864 <p/>
10865 See the
10866 <internallink id="capabilityExamples">Capability Examples</internallink>.
10867 </description>
10868 <origin>jvmdiClone</origin>
10869 <capabilities>
10870 </capabilities>
10871 <parameters>
10872 <param id="capabilities_ptr">
10873 <outptr><struct>jvmtiCapabilities</struct></outptr>
10874 <description>
10875 On return, points to the <jvmti/> capabilities.
10876 </description>
10877 </param>
10878 </parameters>
10879 <errors>
10880 </errors>
10881 </function>
10882
10883 </category>
10884
10885
10886 <category id="timers" label="Timers">
10887
10888 <intro>
10889 These functions provide timing information.
10890 The resolution at which the time is updated is not specified.
10891 They provides nanosecond precision, but not necessarily nanosecond accuracy.
10892 Details about the timers, such as their maximum values, can be accessed with
10893 the timer information functions.
10894 </intro>
10895
10896 <typedef id="jvmtiTimerInfo" label="Timer Info">
10897 <description>
10898 The information function for each timer returns this data structure.
10899 </description>
10900 <field id="max_value">
10901 <jlong/>
10902 <description>
10903 The maximum value the timer can reach.
10904 After this value is reached the timer wraps back to zero.
10905 This is an unsigned value. If tested or printed as a jlong (signed value)
10906 it may appear to be a negative number.
10907 </description>
10908 </field>
10909 <field id="may_skip_forward">
10910 <jboolean/>
10911 <description>
10912 If true, the timer can be externally adjusted and as a result skip forward.
10913 If false, the timer value will never increase faster than real time.
10914 </description>
10915 </field>
10916 <field id="may_skip_backward">
10917 <jboolean/>
10918 <description>
10919 If true, the timer can be externally adjusted and as a result skip backward.
10920 If false, the timer value will be monotonically increasing.
10921 </description>
10922 </field>
10923 <field id="kind">
10924 <enum>jvmtiTimerKind</enum>
10925 <description>
10926 The kind of timer.
10927 On a platform that does not distinguish between user and system time, <datalink
10928 id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10929 is returned.
10930 </description>
10931 </field>
10932 <field id="reserved1">
10933 <jlong/>
10934 <description>
10935 Reserved for future use.
10936 </description>
10937 </field>
10938 <field id="reserved2">
10939 <jlong/>
10940 <description>
10941 Reserved for future use.
10942 </description>
10943 </field>
10944 </typedef>
10945
10946 <intro>
10947 Where the timer kind is --
10948
10949 <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10950 <constant id="JVMTI_TIMER_USER_CPU" num="30">
10951 CPU time that a thread is in user mode.
10952 </constant>
10953 <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10954 CPU time that a thread is in user or system mode.
10955 </constant>
10956 <constant id="JVMTI_TIMER_ELAPSED" num="32">
10957 Elapsed time.
10958 </constant>
10959 </constants>
10960 </intro>
10961
10962 <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe" impl="innative notrace" phase="start" num="134">
10963 <synopsis>Get Current Thread CPU Timer Information</synopsis>
10964 <description>
10965 Get information about the
10966 <functionlink id="GetCurrentThreadCpuTime"/> timer.
10967 The fields of the <datalink id="jvmtiTimerInfo"/> structure
10968 are filled in with details about the timer.
10969 This information is specific to the platform and the implementation of
10970 <functionlink id="GetCurrentThreadCpuTime"/> and thus
10971 does not vary by thread nor does it vary
10972 during a particular invocation of the VM.
10973 <p/>
10974 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10975 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10976 returned by <code>GetCurrentThreadCpuTimerInfo</code>
10977 and <functionlink id="GetThreadCpuTimerInfo"/>
10978 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10979 </description>
10980 <origin>new</origin>
10981 <capabilities>
10982 <required id="can_get_current_thread_cpu_time">
10983 Can get current thread CPU time.
10984 </required>
10985 </capabilities>
10986 <parameters>
10987 <param id="info_ptr">
10988 <outptr><struct>jvmtiTimerInfo</struct></outptr>
10989 <description>
10990 On return, filled with information describing the time
10991 returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10992 </description>
10993 </param>
10994 </parameters>
10995 <errors>
10996 </errors>
10997 </function>
10998
10999 <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
11000 <synopsis>Get Current Thread CPU Time</synopsis>
11001 <description>
11002 Return the CPU time utilized by the current thread.
11003 <p/>
11004 Note that the <functionlink id="GetThreadCpuTime"/>
11005 function provides CPU time for any thread, including
11006 the current thread. <code>GetCurrentThreadCpuTime</code>
11007 exists to support platforms which cannot
11008 supply CPU time for threads other than the current
11009 thread or which have more accurate information for
11010 the current thread (see
11011 <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
11012 <functionlink id="GetThreadCpuTimerInfo"/>).
11013 The current thread may not be a virtual thread. Otherwise, the error code
11014 <errorlink id="JVMTI_ERROR_UNSUPPORTED_OPERATION"></errorlink> will be returned.
11015 On many platforms this call will be equivalent to:
11016 <example>
11017 GetThreadCpuTime(env, NULL, nanos_ptr)
11018 </example>
11019 </description>
11020 <origin>new</origin>
11021 <capabilities>
11022 <required id="can_get_current_thread_cpu_time">
11023 Can get current thread CPU time.
11024 <p/>
11025 If this capability is enabled after threads have started,
11026 the implementation may choose any time up
11027 to and including the time that the capability is enabled
11028 as the point where CPU time collection starts.
11029 <p/>
11030 This capability must be potentially available on any
11031 platform where
11032 <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
11033 is potentially available.
11034 </required>
11035 </capabilities>
11036 <parameters>
11037 <param id="nanos_ptr">
11038 <outptr><jlong/></outptr>
11039 <description>
11040 On return, points to the CPU time used by this thread
11041 in nanoseconds.
11042 This is an unsigned value. If tested or printed as a jlong (signed value)
11043 it may appear to be a negative number.
11044 </description>
11045 </param>
11046 </parameters>
11047 <errors>
11048 <error id="JVMTI_ERROR_UNSUPPORTED_OPERATION">
11049 The current thread is a virtual thread and the implementation does not support
11050 getting the current thread CPU time when the current thread is a virtual thread.
11051 </error>
11052 </errors>
11053 </function>
11054
11055 <function id="GetThreadCpuTimerInfo" num="136">
11056 <synopsis>Get Thread CPU Timer Information</synopsis>
11057 <description>
11058 Get information about the
11059 <functionlink id="GetThreadCpuTime"/> timer.
11060 The fields of the <datalink id="jvmtiTimerInfo"/> structure
11061 are filled in with details about the timer.
11062 This information is specific to the platform and the implementation of
11063 <functionlink id="GetThreadCpuTime"/> and thus
11064 does not vary by thread nor does it vary
11065 during a particular invocation of the VM.
11066 <p/>
11067 Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
11068 and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
11069 returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
11070 and <code>GetThreadCpuTimerInfo</code>
11071 may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
11072 </description>
11073 <origin>new</origin>
11074 <capabilities>
11075 <required id="can_get_thread_cpu_time">
11076 Can get thread CPU time.
11077 </required>
11078 </capabilities>
11079 <parameters>
11080 <param id="info_ptr">
11081 <outptr><struct>jvmtiTimerInfo</struct></outptr>
11082 <description>
11083 On return, filled with information describing the time
11084 returned by <functionlink id="GetThreadCpuTime"/>.
11085 </description>
11086 </param>
11087 </parameters>
11088 <errors>
11089 </errors>
11090 </function>
11091
11092 <function id="GetThreadCpuTime" num="137">
11093 <synopsis>Get Thread CPU Time</synopsis>
11094 <description>
11095 Return the CPU time utilized by the specified thread.
11096 <p/>
11097 Get information about this timer with
11098 <functionlink id="GetThreadCpuTimerInfo"/>.
11099 </description>
11100 <origin>new</origin>
11101 <capabilities>
11102 <required id="can_get_thread_cpu_time">
11103 Can get thread CPU time.
11104 <p/>
11105 If this capability is enabled after threads have started,
11106 the implementation may choose any time up
11107 to and including the time that the capability is enabled
11108 as the point where CPU time collection starts.
11109 </required>
11110 </capabilities>
11111 <parameters>
11112 <param id="thread">
11113 <jthread null="current" impl="noconvert"/>
11114 <description>
11115 The thread to query.
11116 The <code>thread</code> may not be a virtual thread. Otherwise, the error code
11117 <errorlink id="JVMTI_ERROR_UNSUPPORTED_OPERATION"></errorlink> will be returned.
11118 </description>
11119 </param>
11120 <param id="nanos_ptr">
11121 <outptr impl="nonullcheck"><jlong/></outptr>
11122 <description>
11123 On return, points to the CPU time used by the specified thread
11124 in nanoseconds.
11125 This is an unsigned value. If tested or printed as a jlong (signed value)
11126 it may appear to be a negative number.
11127 </description>
11128 </param>
11129 </parameters>
11130 <errors>
11131 <error id="JVMTI_ERROR_UNSUPPORTED_OPERATION">
11132 <paramlink id="thread"/> is a virtual thread and the implementation does not
11133 support getting the thread CPU time of a virtual thread.
11134 </error>
11135 </errors>
11136 </function>
11137
11138 <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
11139 <synopsis>Get Timer Information</synopsis>
11140 <description>
11141 Get information about the
11142 <functionlink id="GetTime"/> timer.
11143 The fields of the <datalink id="jvmtiTimerInfo"/> structure
11144 are filled in with details about the timer.
11145 This information will not change during a particular invocation of the VM.
11146 </description>
11147 <origin>new</origin>
11148 <capabilities>
11149 </capabilities>
11150 <parameters>
11151 <param id="info_ptr">
11152 <outptr><struct>jvmtiTimerInfo</struct></outptr>
11153 <description>
11154 On return, filled with information describing the time
11155 returned by <functionlink id="GetTime"/>.
11156 </description>
11157 </param>
11158 </parameters>
11159 <errors>
11160 </errors>
11161 </function>
11162
11163 <function id="GetTime" phase="any" callbacksafe="safe" num="139">
11164 <synopsis>Get Time</synopsis>
11165 <description>
11166 Return the current value of the system timer, in nanoseconds.
11167 <p/>
11168 The value returned represents nanoseconds since some fixed but
11169 arbitrary time (perhaps in the future, so values may be
11170 negative). This function provides nanosecond precision, but not
11171 necessarily nanosecond accuracy. No guarantees are made about
11172 how frequently values change.
11173 <p/>
11174 Get information about this timer with
11175 <functionlink id="GetTimerInfo"/>.
11176 </description>
11177 <origin>new</origin>
11178 <capabilities>
11179 </capabilities>
11180 <parameters>
11181 <param id="nanos_ptr">
11182 <outptr><jlong/></outptr>
11183 <description>
11184 On return, points to the time in nanoseconds.
11185 This is an unsigned value. If tested or printed as a jlong (signed value)
11186 it may appear to be a negative number.
11187 </description>
11188 </param>
11189 </parameters>
11190 <errors>
11191 </errors>
11192 </function>
11193
11194 <function id="GetAvailableProcessors" phase="any" num="144">
11195 <synopsis>Get Available Processors</synopsis>
11196 <description>
11197 Returns the number of processors available to the Java virtual machine.
11198 <p/>
11199 This value may change during a particular invocation of the virtual machine.
11200 Applications that are sensitive to the number of available processors should
11201 therefore occasionally poll this property.
11202 </description>
11203 <origin>new</origin>
11204 <capabilities>
11205 </capabilities>
11206 <parameters>
11207 <param id="processor_count_ptr">
11208 <outptr><jint/></outptr>
11209 <description>
11210 On return, points to the maximum number of processors available to the
11211 virtual machine; never smaller than one.
11212 </description>
11213 </param>
11214 </parameters>
11215 <errors>
11216 </errors>
11217 </function>
11218
11219 </category>
11220
11221
11222 <category id="classLoaderSearch" label="Class Loader Search">
11223
11224 <intro>
11225 These functions allow the agent to add to the locations that a class loader searches for a class.
11226 This is useful for installing instrumentation under the correct class loader.
11227 </intro>
11228
11229 <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
11230 <synopsis>Add To Bootstrap Class Loader Search</synopsis>
11231 <description>
11232 This function can be used to cause instrumentation classes to be defined by the
11233 bootstrap class loader. See <vmspec chapter="5.3.1"/>.
11234 After the bootstrap
11235 class loader unsuccessfully searches for a class, the specified platform-dependent
11236 search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in
11237 the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments,
11238 the segments will be searched in the order that this function was called.
11239 <p/>
11240 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
11241 search path segment to be searched after the bootstrap class loader unsuccessfully searches
11242 for a class. The segment is typically a directory or JAR file.
11243 <p/>
11244 In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
11245 path to a <externallink id="jar/jar.html">
11246 JAR file</externallink>. The agent should take care that the JAR file does not
11247 contain any classes or resources other than those to be defined by the bootstrap
11248 class loader for the purposes of instrumentation.
11249 <p/>
11250 <vmspec/> specifies that a subsequent attempt to resolve a symbolic
11251 reference that the Java virtual machine has previously unsuccessfully attempted
11252 to resolve always fails with the same error that was thrown as a result of the
11253 initial resolution attempt. Consequently, if the JAR file contains an entry
11254 that corresponds to a class for which the Java virtual machine has
11255 unsuccessfully attempted to resolve a reference, then subsequent attempts to
11256 resolve that reference will fail with the same error as the initial attempt.
11257 </description>
11258 <origin>new</origin>
11259 <capabilities>
11260 </capabilities>
11261 <parameters>
11262 <param id="segment">
11263 <inbuf><char/></inbuf>
11264 <description>
11265 The platform-dependent search path segment, encoded as a
11266 <internallink id="mUTF">modified UTF-8</internallink> string.
11267 </description>
11268 </param>
11269 </parameters>
11270 <errors>
11271 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11272 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
11273 existing JAR file is an invalid path.
11274 </error>
11275 </errors>
11276 </function>
11277
11278 <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
11279 <synopsis>Add To System Class Loader Search</synopsis>
11280 <description>
11281 This function can be used to cause instrumentation classes to be
11282 defined by the system class loader. See <vmspec chapter="5.3.2"/>.
11283 After the class loader unsuccessfully searches for a class, the specified platform-dependent search
11284 path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the
11285 <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the
11286 segments will be searched in the order that this function was called.
11287 <p/>
11288 In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
11289 search path segment to be searched after the system class loader unsuccessfully searches
11290 for a class. The segment is typically a directory or JAR file.
11291 <p/>
11292 In the live phase the <paramlink id="segment"/> is a platform-dependent path to a
11293 <externallink id="jar/jar.html">JAR file</externallink> to be
11294 searched after the system class loader unsuccessfully searches for a class. The agent should
11295 take care that the JAR file does not contain any classes or resources other than those to be
11296 defined by the system class loader for the purposes of instrumentation.
11297 <p/>
11298 In the live phase the system class loader supports adding a JAR file to be searched if
11299 the system class loader implements a method name <code>appendToClassPathForInstrumentation</code>
11300 which takes a single parameter of type <code>java.lang.String</code>. The method is not required
11301 to have <code>public</code> access.
11302 <p/>
11303 <vmspec/> specifies that a subsequent attempt to resolve a symbolic
11304 reference that the Java virtual machine has previously unsuccessfully attempted
11305 to resolve always fails with the same error that was thrown as a result of the
11306 initial resolution attempt. Consequently, if the JAR file contains an entry
11307 that corresponds to a class for which the Java virtual machine has
11308 unsuccessfully attempted to resolve a reference, then subsequent attempts to
11309 resolve that reference will fail with the same error as the initial attempt.
11310 </description>
11311 <origin>new</origin>
11312 <capabilities>
11313 </capabilities>
11314 <parameters>
11315 <param id="segment">
11316 <inbuf><char/></inbuf>
11317 <description>
11318 The platform-dependent search path segment, encoded as a
11319 <internallink id="mUTF">modified UTF-8</internallink> string.
11320 </description>
11321 </param>
11322 </parameters>
11323 <errors>
11324 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11325 <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
11326 existing JAR file is an invalid path.
11327 </error>
11328 <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
11329 Operation not supported by the system class loader.
11330 </error>
11331 </errors>
11332 </function>
11333
11334 </category>
11335
11336
11337 <category id="props" label="System Properties">
11338
11339 <intro>
11340 These functions get and set system properties.
11341 </intro>
11342
11343 <function id="GetSystemProperties" phase="onload" num="130">
11344 <synopsis>Get System Properties</synopsis>
11345 <description>
11346 The list of VM system property keys which may be used with
11347 <functionlink id="GetSystemProperty"/> is returned.
11348 It is strongly recommended that virtual machines provide the
11349 following property keys:
11350 <ul>
11351 <li><code>java.vm.vendor</code></li>
11352 <li><code>java.vm.version</code></li>
11353 <li><code>java.vm.name</code></li>
11354 <li><code>java.vm.info</code></li>
11355 <li><code>java.library.path</code></li>
11356 <li><code>java.class.path</code></li>
11357 </ul>
11358 Provides access to system properties defined by and used
11359 by the VM.
11360 Properties set on the command-line are included.
11361 This allows getting and setting of these properties
11362 before the VM even begins executing bytecodes.
11363 Since this is a VM view of system properties, the set of available
11364 properties will usually be different than that
11365 in <code>java.lang.System.getProperties</code>.
11366 JNI method invocation may be used to access
11367 <code>java.lang.System.getProperties</code>.
11368 <p/>
11369 The set of properties may grow during execution.
11370 </description>
11371 <origin>new</origin>
11372 <capabilities>
11373 </capabilities>
11374 <parameters>
11375 <param id="count_ptr">
11376 <outptr><jint/></outptr>
11377 <description>
11378 On return, points to the number of property keys returned.
11379 </description>
11380 </param>
11381 <param id="property_ptr">
11382 <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
11383 <description>
11384 On return, points to an array of property keys, encoded as
11385 <internallink id="mUTF">modified UTF-8</internallink> strings.
11386 </description>
11387 </param>
11388 </parameters>
11389 <errors>
11390 </errors>
11391 </function>
11392
11393 <function id="GetSystemProperty" phase="onload" num="131">
11394 <synopsis>Get System Property</synopsis>
11395 <description>
11396 Return a VM system property value given the property key.
11397 <p/>
11398 The function <functionlink id="GetSystemProperties"/>
11399 returns the set of property keys which may be used.
11400 The properties which can be retrieved may grow during
11401 execution.
11402 <p/>
11403 Since this is a VM view of system properties, the values
11404 of properties may differ from that returned by
11405 <code>java.lang.System.getProperty(String)</code>.
11406 A typical VM might copy the values of the VM system
11407 properties into the <code>Properties</code> held by
11408 <code>java.lang.System</code> during the initialization
11409 of that class. Thereafter any changes to the VM system
11410 properties (with <functionlink id="SetSystemProperty"/>)
11411 or the <code>java.lang.System</code> system properties
11412 (with <code>java.lang.System.setProperty(String,String)</code>)
11413 would cause the values to diverge.
11414 JNI method invocation may be used to access
11415 <code>java.lang.System.getProperty(String)</code>.
11416 </description>
11417 <origin>new</origin>
11418 <capabilities>
11419 </capabilities>
11420 <parameters>
11421 <param id="property">
11422 <inbuf><char/></inbuf>
11423 <description>
11424 The key of the property to retrieve, encoded as a
11425 <internallink id="mUTF">modified UTF-8</internallink> string.
11426 </description>
11427 </param>
11428 <param id="value_ptr">
11429 <allocbuf><char/></allocbuf>
11430 <description>
11431 On return, points to the property value, encoded as a
11432 <internallink id="mUTF">modified UTF-8</internallink> string.
11433 </description>
11434 </param>
11435 </parameters>
11436 <errors>
11437 <error id="JVMTI_ERROR_NOT_AVAILABLE">
11438 This property is not available.
11439 Use <functionlink id="GetSystemProperties"/> to find available properties.
11440 </error>
11441 </errors>
11442 </function>
11443
11444 <function id="SetSystemProperty" phase="onloadOnly" num="132">
11445 <synopsis>Set System Property</synopsis>
11446 <description>
11447 Set a VM system property value.
11448 <p/>
11449 The function <functionlink id="GetSystemProperties"/>
11450 returns the set of property keys, some of these may be settable.
11451 See <functionlink id="GetSystemProperty"/>.
11452 </description>
11453 <origin>new</origin>
11454 <capabilities>
11455 </capabilities>
11456 <parameters>
11457 <param id="property">
11458 <inbuf><char/></inbuf>
11459 <description>
11460 The key of the property, encoded as a
11461 <internallink id="mUTF">modified UTF-8</internallink> string.
11462 </description>
11463 </param>
11464 <param id="value_ptr">
11465 <inbuf>
11466 <char/>
11467 <nullok>
11468 do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
11469 if the property is not writeable
11470 </nullok>
11471 </inbuf>
11472 <description>
11473 The property value to set, encoded as a
11474 <internallink id="mUTF">modified UTF-8</internallink> string.
11475 </description>
11476 </param>
11477 </parameters>
11478 <errors>
11479 <error id="JVMTI_ERROR_NOT_AVAILABLE">
11480 This property is not available or is not writeable.
11481 </error>
11482 </errors>
11483 </function>
11484
11485 </category>
11486
11487 <category id="general" label="General">
11488
11489 <intro>
11490 </intro>
11491
11492 <function id="GetPhase" jkernel="yes" phase="any" num="133">
11493 <synopsis>Get Phase</synopsis>
11494 <description>
11495 Return the current phase of VM execution.
11496 The phases proceed in sequence:
11497 <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
11498 <constant id="JVMTI_PHASE_ONLOAD" num="1">
11499 <code>OnLoad</code> phase: while in the
11500 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
11501 or, for statically linked agents, the <internallink id="onload">
11502 <code>Agent_OnLoad_<agent-lib-name>
11503 </code></internallink> function.
11504 </constant>
11505 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
11506 Primordial phase: between return from <code>Agent_OnLoad</code>
11507 or <code>Agent_OnLoad_<agent-lib-name></code> and the
11508 <code>VMStart</code> event.
11509 </constant>
11510 <constant id="JVMTI_PHASE_START" num="6">
11511 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
11512 is sent and until the <code>VMInit</code> event is sent.
11513 </constant>
11514 <constant id="JVMTI_PHASE_LIVE" num="4">
11515 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
11516 and until the <eventlink id="VMDeath"></eventlink> event returns.
11517 </constant>
11518 <constant id="JVMTI_PHASE_DEAD" num="8">
11519 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
11520 start-up failure.
11521 </constant>
11522 </constants>
11523 In the case of start-up failure the VM will proceed directly to the dead
11524 phase skipping intermediate phases and neither a <code>VMInit</code> nor
11525 <code>VMDeath</code> event will be sent.
11526 <p/>
11527 Most <jvmti/> functions operate only in the live phase.
11528 The following functions operate in either the <code>OnLoad</code> or live phases:
11529 <functionphaselist phase="onload"/>
11530 The following functions operate in only the <code>OnLoad</code> phase:
11531 <functionphaselist phase="onloadOnly"/>
11532 The following functions operate in the start or live phases:
11533 <functionphaselist phase="start"/>
11534 The following functions operate in any phase:
11535 <functionphaselist phase="any"/>
11536 JNI functions (except the Invocation API) must only be used in the start or live phases.
11537 <p/>
11538 Most <jvmti/> events are sent only in the live phase.
11539 The following events operate in others phases:
11540 <eventphaselist phase="start"/>
11541 <eventphaselist phase="any"/>
11542 </description>
11543 <origin>new</origin>
11544 <capabilities>
11545 </capabilities>
11546 <parameters>
11547 <param id="phase_ptr">
11548 <outptr><enum>jvmtiPhase</enum></outptr>
11549 <description>
11550 On return, points to the phase.
11551 </description>
11552 </param>
11553 </parameters>
11554 <errors>
11555 </errors>
11556 </function>
11557
11558 <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
11559 <synopsis>Dispose Environment</synopsis>
11560 <description>
11561 Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
11562 (see <internallink id="environments"><jvmti/> Environments</internallink>).
11563 Dispose of any resources held by the environment.
11564 <issue>
11565 What resources are reclaimed? What is undone?
11566 Breakpoints,watchpoints removed?
11567 </issue>
11568 Threads suspended by this environment are not resumed by this call,
11569 this must be done explicitly by the agent.
11570 Memory allocated by this environment via calls to <jvmti/> functions
11571 is not released, this can be done explicitly by the agent
11572 by calling <functionlink id="Deallocate"/>.
11573 Raw monitors created by this environment are not destroyed,
11574 this can be done explicitly by the agent
11575 by calling <functionlink id="DestroyRawMonitor"/>.
11576 The state of threads waiting on raw monitors created by this environment
11577 are not affected.
11578 <p/>
11579 Any <functionlink id="SetNativeMethodPrefix">native method
11580 prefixes</functionlink> for this environment will be unset;
11581 the agent must remove any prefixed native methods before
11582 dispose is called.
11583 <p/>
11584 Any <internallink id="capability">capabilities</internallink>
11585 held by this environment are relinquished.
11586 <p/>
11587 Events enabled by this environment will no longer be sent, however
11588 event handlers currently running will continue to run. Caution must
11589 be exercised in the design of event handlers whose environment may
11590 be disposed and thus become invalid during their execution.
11591 <p/>
11592 This environment may not be used after this call.
11593 This call returns to the caller.
11594 </description>
11595 <origin>new</origin>
11596 <capabilities>
11597 </capabilities>
11598 <parameters>
11599 </parameters>
11600 <errors>
11601 </errors>
11602 </function>
11603
11604 <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
11605 <synopsis>Set Environment Local Storage</synopsis>
11606 <description>
11607 The VM stores a pointer value associated with each environment.
11608 This pointer value is called <i>environment-local storage</i>.
11609 This value is <code>NULL</code> unless set with this function.
11610 Agents can allocate memory in which they store environment specific
11611 information. By setting environment-local storage it can then be
11612 accessed with
11613 <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
11614 <p/>
11615 Called by the agent to set the value of the <jvmti/>
11616 environment-local storage. <jvmti/> supplies to the agent a pointer-size
11617 environment-local storage that can be used to record per-environment
11618 information.
11619 </description>
11620 <origin>new</origin>
11621 <capabilities>
11622 </capabilities>
11623 <parameters>
11624 <param id="data">
11625 <inbuf>
11626 <void/>
11627 <nullok>value is set to <code>NULL</code></nullok>
11628 </inbuf>
11629 <description>
11630 The value to be entered into the environment-local storage.
11631 </description>
11632 </param>
11633 </parameters>
11634 <errors>
11635 </errors>
11636 </function>
11637
11638 <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
11639 <synopsis>Get Environment Local Storage</synopsis>
11640 <description>
11641 Called by the agent to get the value of the <jvmti/> environment-local
11642 storage.
11643 </description>
11644 <origin>new</origin>
11645 <capabilities>
11646 </capabilities>
11647 <parameters>
11648 <param id="data_ptr">
11649 <agentbuf><void/></agentbuf>
11650 <description>
11651 Pointer through which the value of the environment local
11652 storage is returned.
11653 If environment-local storage has not been set with
11654 <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned
11655 pointer is <code>NULL</code>.
11656 </description>
11657 </param>
11658 </parameters>
11659 <errors>
11660 </errors>
11661 </function>
11662
11663 <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
11664 <synopsis>Get Version Number</synopsis>
11665 <description>
11666 Return the <jvmti/> version via <code>version_ptr</code>.
11667 The return value is the version identifier.
11668 The version identifier includes major, minor and micro
11669 version as well as the interface type.
11670 <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
11671 <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
11672 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
11673 </constant>
11674 <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
11675 Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
11676 </constant>
11677 </constants>
11678 <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
11679 <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
11680 Mask to extract interface type.
11681 The value of the version returned by this function masked with
11682 <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
11683 <code>JVMTI_VERSION_INTERFACE_JVMTI</code>
11684 since this is a <jvmti/> function.
11685 </constant>
11686 <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
11687 Mask to extract major version number.
11688 </constant>
11689 <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
11690 Mask to extract minor version number.
11691 </constant>
11692 <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
11693 Mask to extract micro version number.
11694 </constant>
11695 </constants>
11696 <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
11697 <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
11698 Shift to extract major version number.
11699 </constant>
11700 <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
11701 Shift to extract minor version number.
11702 </constant>
11703 <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
11704 Shift to extract micro version number.
11705 </constant>
11706 </constants>
11707 </description>
11708 <origin>jvmdi</origin>
11709 <capabilities>
11710 </capabilities>
11711 <parameters>
11712 <param id="version_ptr">
11713 <outptr><jint/></outptr>
11714 <description>
11715 On return, points to the <jvmti/> version.
11716 </description>
11717 </param>
11718 </parameters>
11719 <errors>
11720 </errors>
11721 </function>
11722
11723
11724 <function id="GetErrorName" phase="any" num="128">
11725 <synopsis>Get Error Name</synopsis>
11726 <description>
11727 Return the symbolic name for an
11728 <internallink id="ErrorSection">error code</internallink>.
11729 <p/>
11730 For example
11731 <code>GetErrorName(env, JVMTI_ERROR_NONE, &err_name)</code>
11732 would return in <code>err_name</code> the string
11733 <code>"JVMTI_ERROR_NONE"</code>.
11734 </description>
11735 <origin>new</origin>
11736 <capabilities>
11737 </capabilities>
11738 <parameters>
11739 <param id="error">
11740 <enum>jvmtiError</enum>
11741 <description>
11742 The error code.
11743 </description>
11744 </param>
11745 <param id="name_ptr">
11746 <allocbuf><char/></allocbuf>
11747 <description>
11748 On return, points to the error name.
11749 The name is encoded as a
11750 <internallink id="mUTF">modified UTF-8</internallink> string,
11751 but is restricted to the ASCII subset.
11752 </description>
11753 </param>
11754 </parameters>
11755 <errors>
11756 </errors>
11757 </function>
11758
11759 <function id="SetVerboseFlag" phase="any" num="150">
11760 <synopsis>Set Verbose Flag</synopsis>
11761 <description>
11762 <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11763 <constant id="JVMTI_VERBOSE_OTHER" num="0">
11764 Verbose output other than the below.
11765 </constant>
11766 <constant id="JVMTI_VERBOSE_GC" num="1">
11767 Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11768 </constant>
11769 <constant id="JVMTI_VERBOSE_CLASS" num="2">
11770 Verbose class loading output, like that specified with <code>-verbose:class</code>.
11771 </constant>
11772 <constant id="JVMTI_VERBOSE_JNI" num="4">
11773 Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11774 </constant>
11775 </constants>
11776 Control verbose output.
11777 This is the output which typically is sent to <code>stderr</code>.
11778 </description>
11779 <origin>new</origin>
11780 <capabilities>
11781 </capabilities>
11782 <parameters>
11783 <param id="flag">
11784 <enum>jvmtiVerboseFlag</enum>
11785 <description>
11786 Which verbose flag to set.
11787 </description>
11788 </param>
11789 <param id="value">
11790 <jboolean/>
11791 <description>
11792 New value of the flag.
11793 </description>
11794 </param>
11795 </parameters>
11796 <errors>
11797 </errors>
11798 </function>
11799
11800
11801 <function id="GetJLocationFormat" phase="any" num="129">
11802 <synopsis>Get JLocation Format</synopsis>
11803 <description>
11804 Although the greatest functionality is achieved with location information
11805 referencing the virtual machine bytecode index, the definition of
11806 <code>jlocation</code> has intentionally been left unconstrained to allow VM
11807 implementations that do not have this information.
11808 <p/>
11809 This function describes the representation of <code>jlocation</code> used in this VM.
11810 If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>,
11811 <code>jlocation</code>s can
11812 be used as in indices into the array returned by
11813 <functionlink id="GetBytecodes"></functionlink>.
11814 <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11815 <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11816 <code>jlocation</code> values represent virtual machine
11817 bytecode indices--that is, offsets into the
11818 virtual machine code for a method.
11819 </constant>
11820 <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11821 <code>jlocation</code> values represent native machine
11822 program counter values.
11823 </constant>
11824 <constant id="JVMTI_JLOCATION_OTHER" num="0">
11825 <code>jlocation</code> values have some other representation.
11826 </constant>
11827 </constants>
11828 </description>
11829 <origin>new</origin>
11830 <capabilities>
11831 </capabilities>
11832 <parameters>
11833 <param id="format_ptr">
11834 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11835 <description>
11836 On return, points to the format identifier for <code>jlocation</code> values.
11837 </description>
11838 </param>
11839 </parameters>
11840 <errors>
11841 </errors>
11842 </function>
11843
11844 </category>
11845
11846 <category id="heap_monitoring" label="Heap Monitoring">
11847 <function id="SetHeapSamplingInterval" phase="onload" num="156" since="11">
11848 <synopsis>Set Heap Sampling Interval</synopsis>
11849 <description>
11850 Generate a <eventlink id="SampledObjectAlloc"/> event when objects are allocated.
11851 Each thread keeps a counter of bytes allocated. The event will only be generated
11852 when that counter exceeds an average of <paramlink id="sampling_interval"></paramlink>
11853 since the last sample.
11854 <p/>
11855 Setting <paramlink id="sampling_interval"></paramlink> to 0 will cause an event to be
11856 generated by each allocation supported by the system once the new interval is taken into account.
11857 <p/>
11858 Note that updating the new sampling interval might take various number of allocations
11859 to provoke internal data structure updates. Therefore it is important to
11860 consider the sampling interval as an average. This includes the interval 0, where events
11861 might not be generated straight away for each allocation.
11862 </description>
11863 <origin>new</origin>
11864 <capabilities>
11865 <required id="can_generate_sampled_object_alloc_events"></required>
11866 </capabilities>
11867 <parameters>
11868 <param id="sampling_interval">
11869 <jint/>
11870 <description>
11871 The sampling interval in bytes. The sampler uses a statistical approach to
11872 generate an event, on average, once for every <paramlink id="sampling_interval"/> bytes of
11873 memory allocated by a given thread.
11874 <p/>
11875 Once the new sampling interval is taken into account, 0 as a sampling interval will generate
11876 a sample for every allocation.
11877 <p/>
11878 Note: The overhead of this feature is directly correlated with the sampling interval.
11879 A high sampling interval, such as 1024 bytes, will incur a high overhead.
11880 A lower interval, such as 1024KB, will have a much lower overhead. Sampling should only
11881 be used with an understanding that it may impact performance.
11882 </description>
11883 </param>
11884 </parameters>
11885 <errors>
11886 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11887 <paramlink id="sampling_interval"></paramlink> is less than zero.
11888 </error>
11889 </errors>
11890 </function>
11891 </category>
11892
11893 </functionsection>
11894
11895 <errorsection label="Error Reference">
11896 <intro>
11897 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11898 <p/>
11899 It is the responsibility of the agent to call <jvmti/> functions with
11900 valid parameters and in the proper context (calling thread is attached,
11901 phase is correct, etc.).
11902 Detecting some error conditions may be difficult, inefficient, or
11903 impossible for an implementation.
11904 The errors listed in
11905 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11906 must be detected by the implementation.
11907 All other errors represent the recommended response to the error
11908 condition.
11909 </intro>
11910
11911 <errorcategory id="universal-error" label="Universal Errors">
11912 <intro>
11913 The following errors may be returned by any function
11914 </intro>
11915
11916 <errorid id="JVMTI_ERROR_NONE" num="0">
11917 No error has occurred. This is the error code that is returned
11918 on successful completion of the function.
11919 </errorid>
11920 <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11921 Pointer is unexpectedly <code>NULL</code>.
11922 </errorid>
11923 <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11924 The function attempted to allocate memory and no more memory was
11925 available for allocation.
11926 </errorid>
11927 <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11928 The desired functionality has not been enabled in this virtual machine.
11929 </errorid>
11930 <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11931 The thread being used to call this function is not attached
11932 to the virtual machine. Calls must be made from attached threads.
11933 See <code>AttachCurrentThread</code> in the JNI invocation API.
11934 </errorid>
11935 <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11936 The <jvmti/> environment provided is no longer connected or is
11937 not an environment.
11938 </errorid>
11939 <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11940 The desired functionality is not available in the current
11941 <functionlink id="GetPhase">phase</functionlink>.
11942 Always returned if the virtual machine has completed running.
11943 </errorid>
11944 <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11945 An unexpected internal error has occurred.
11946 </errorid>
11947 </errorcategory>
11948
11949 <errorcategory id="reqerrors" label="Function Specific Required Errors">
11950 <intro>
11951 The following errors are returned by some <jvmti/> functions and must
11952 be returned by the implementation when the condition occurs.
11953 </intro>
11954
11955 <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11956 Invalid priority.
11957 </errorid>
11958 <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11959 Thread was not suspended.
11960 </errorid>
11961 <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11962 Thread already suspended.
11963 </errorid>
11964 <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11965 This operation requires the thread to be alive--that is,
11966 it must be started and not yet terminated.
11967 </errorid>
11968 <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11969 The class has been loaded but not yet prepared.
11970 </errorid>
11971 <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11972 There are no Java programming language or JNI stack frames at the specified depth.
11973 </errorid>
11974 <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11975 Information about the frame is not available (e.g. for native frames).
11976 </errorid>
11977 <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11978 Item already set.
11979 </errorid>
11980 <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11981 Desired element (e.g. field or breakpoint) not found
11982 </errorid>
11983 <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11984 This thread doesn't own the raw monitor.
11985 </errorid>
11986 <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11987 The call has been interrupted before completion.
11988 </errorid>
11989 <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11990 The class cannot be modified.
11991 </errorid>
11992 <errorid id="JVMTI_ERROR_UNMODIFIABLE_MODULE" num="80">
11993 The module cannot be modified.
11994 </errorid>
11995 <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11996 The functionality is not available in this virtual machine.
11997 </errorid>
11998 <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11999 The requested information is not available.
12000 </errorid>
12001 <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
12002 The specified event type ID is not recognized.
12003 </errorid>
12004 <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
12005 The requested information is not available for native method.
12006 </errorid>
12007 <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
12008 The class loader does not support this operation.
12009 </errorid>
12010 </errorcategory>
12011
12012 <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
12013 <intro>
12014 The following errors are returned by some <jvmti/> functions.
12015 They are returned in the event of invalid parameters passed by the
12016 agent or usage in an invalid context.
12017 An implementation is not required to detect these errors.
12018 </intro>
12019
12020 <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
12021 The passed thread is not a valid thread.
12022 </errorid>
12023 <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
12024 Invalid field.
12025 </errorid>
12026 <errorid id="JVMTI_ERROR_INVALID_MODULE" num="26">
12027 Invalid module.
12028 </errorid>
12029 <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
12030 Invalid method.
12031 </errorid>
12032 <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
12033 Invalid location.
12034 </errorid>
12035 <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
12036 Invalid object.
12037 </errorid>
12038 <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
12039 Invalid class.
12040 </errorid>
12041 <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
12042 The variable is not an appropriate type for the function used.
12043 </errorid>
12044 <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
12045 Invalid slot.
12046 </errorid>
12047 <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
12048 The capability being used is false in this environment.
12049 </errorid>
12050 <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
12051 Thread group invalid.
12052 </errorid>
12053 <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
12054 Invalid raw monitor.
12055 </errorid>
12056 <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
12057 Illegal argument.
12058 </errorid>
12059 <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
12060 The state of the thread has been modified, and is now inconsistent.
12061 </errorid>
12062 <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
12063 A new class file has a version number not supported by this VM.
12064 </errorid>
12065 <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
12066 A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
12067 </errorid>
12068 <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
12069 The new class file definitions would lead to a circular
12070 definition (the VM would return a <code>ClassCircularityError</code>).
12071 </errorid>
12072 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
12073 A new class file would require adding a method.
12074 </errorid>
12075 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
12076 A new class version changes a field.
12077 </errorid>
12078 <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
12079 The class bytes fail verification.
12080 </errorid>
12081 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
12082 A direct superclass is different for the new class
12083 version, or the set of directly implemented
12084 interfaces is different.
12085 </errorid>
12086 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
12087 A new class version does not declare a method
12088 declared in the old class version.
12089 </errorid>
12090 <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
12091 The class name defined in the new class file is
12092 different from the name in the old class object.
12093 </errorid>
12094 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
12095 A new class version has different modifiers.
12096 </errorid>
12097 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
12098 A method in the new class version has different modifiers
12099 than its counterpart in the old class version.
12100 </errorid>
12101 <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED" num="72">
12102 A new class version has unsupported differences in class attributes.
12103 </errorid>
12104 <errorid id="JVMTI_ERROR_UNSUPPORTED_OPERATION" num="73">
12105 Functionality is unsupported in this implementation.
12106 </errorid>
12107 </errorcategory>
12108 </errorsection>
12109
12110 <eventsection label="Events">
12111 <intro label="Handling Events" id="eventIntro">
12112 Agents can be informed of many events that occur in application
12113 programs.
12114 <p/>
12115 To handle events, designate a set of callback functions with
12116 <functionlink id="SetEventCallbacks"></functionlink>.
12117 For each event the corresponding callback function will be
12118 called.
12119 Arguments to the callback function provide additional
12120 information about the event.
12121 <p/>
12122 The callback function is usually called from within an application
12123 thread. The <jvmti/> implementation does not
12124 queue events in any way. This means
12125 that event callback functions must be written
12126 carefully. Here are some general guidelines. See
12127 the individual event descriptions for further
12128 suggestions.
12129 <p/>
12130 <ul>
12131 <li>Any exception thrown during the execution of an event callback can
12132 overwrite any current pending exception in the current application thread.
12133 Care must be taken to preserve a pending exception
12134 when an event callback makes a JNI call that might generate an exception.
12135 </li>
12136 <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
12137 not queue events. If an agent needs to process events one at a time, it
12138 can use a raw monitor inside the
12139 event callback functions to serialize event processing.
12140 </li>
12141 <li>Event callback functions that execute JNI's FindClass function to load
12142 classes need to note that FindClass locates the class loader associated
12143 with the current native method. For the purposes of class loading, an
12144 event callback that includes a JNI environment as a parameter to the
12145 callback will treated as if it is a native call, where the native method
12146 is in the class of the event thread's current frame.
12147 </li>
12148 </ul>
12149 <p/>
12150 Some <jvmti/> events identify objects with JNI references.
12151 All references
12152 in <jvmti/> events are JNI local references and will become invalid
12153 after the event callback returns.
12154 Unless stated otherwise, memory referenced by pointers sent in event
12155 callbacks may not be referenced after the event callback returns.
12156 <p/>
12157 Except where stated otherwise, events are delivered on the thread
12158 that caused the event.
12159 Events are sent at the time they occur.
12160 The specification for each event includes the set of
12161 <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
12162 if an event triggering activity occurs during another phase, no event
12163 is sent.
12164 <p/>
12165 A thread that generates an event does not change its execution status
12166 (for example, the event does not cause the thread to be suspended).
12167 If an agent wishes the event to result in suspension, then the agent
12168 is responsible for explicitly suspending the thread with
12169 <functionlink id="SuspendThread"></functionlink>.
12170 <p/>
12171 If an event is enabled in multiple environments, the event will be sent
12172 to each agent in the order that the environments were created.
12173 </intro>
12174
12175 <intro label="Enabling Events" id="enablingevents">
12176 All events are initially disabled. In order to receive any
12177 event:
12178 <ul>
12179 <li>
12180 If the event requires a capability, that capability must
12181 be added with
12182 <functionlink id="AddCapabilities"></functionlink>.
12183 </li>
12184 <li>
12185 A callback for the event must be set with
12186 <functionlink id="SetEventCallbacks"></functionlink>.
12187 </li>
12188 <li>
12189 The event must be enabled with
12190 <functionlink id="SetEventNotificationMode"></functionlink>.
12191 </li>
12192 </ul>
12193 </intro>
12194
12195 <intro label="Multiple Co-located Events" id="eventorder">
12196 In many situations it is possible for multiple events to occur
12197 at the same location in one thread. When this happens, all the events
12198 are reported through the event callbacks in the order specified in this section.
12199 <p/>
12200 If the current location is at the entry point of a method, the
12201 <eventlink id="MethodEntry"></eventlink> event is reported before
12202 any other event at the current location in the same thread.
12203 <p/>
12204 If an exception catch has been detected at the current location,
12205 either because it is the beginning of a catch clause or a native method
12206 that cleared a pending exception has returned, the
12207 <code>exceptionCatch</code> event is reported before
12208 any other event at the current location in the same thread.
12209 <p/>
12210 If a <code>singleStep</code> event or
12211 <code>breakpoint</code> event is triggered at the
12212 current location, the event is defined to occur
12213 immediately before the code at the current location is executed.
12214 These events are reported before any events which are triggered
12215 by the execution of code at the current location in the same
12216 thread (specifically:
12217 <code>exception</code>,
12218 <code>fieldAccess</code>, and
12219 <code>fieldModification</code>).
12220 If both a step and breakpoint event are triggered for the same thread and
12221 location, the step event is reported before the breakpoint event.
12222 <p/>
12223 If the current location is the exit point of a method (that is, the last
12224 location before returning to the caller), the
12225 <eventlink id="MethodExit"></eventlink> event and
12226 the <eventlink id="FramePop"></eventlink> event (if requested)
12227 are reported after all other events at the current location in the same
12228 thread. There is no specified ordering of these two events
12229 with respect to each other.
12230 <p/>
12231 Co-located events can be triggered during the processing of some other
12232 event by the agent at the same location in the same thread.
12233 If such an event, of type <i>y</i>, is triggered during the processing of
12234 an event of type <i>x</i>, and if <i>x</i>
12235 precedes <i>y</i> in the ordering specified above, the co-located event
12236 <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
12237 <i>y</i>, <i>y</i> is not reported for the current thread and location.
12238 For example, if a breakpoint is set at the current location
12239 during the processing of <eventlink id="SingleStep"></eventlink>,
12240 that breakpoint will be reported before the thread moves off the current
12241 location.
12242 <p/>The following events are never considered to be co-located with
12243 other events.
12244 <ul>
12245 <li><eventlink id="VMStart"></eventlink></li>
12246 <li><eventlink id="VMInit"></eventlink></li>
12247 <li><eventlink id="VMDeath"></eventlink></li>
12248 <li><eventlink id="ThreadStart"></eventlink></li>
12249 <li><eventlink id="ThreadEnd"></eventlink></li>
12250 <li><eventlink id="ClassLoad"></eventlink></li>
12251 <li><eventlink id="ClassPrepare"></eventlink></li>
12252 </ul>
12253 </intro>
12254
12255 <intro label="Event Callbacks" id="jvmtiEventCallbacks">
12256 The event callback structure below is used to specify the handler function
12257 for events. It is set with the
12258 <functionlink id="SetEventCallbacks"></functionlink> function.
12259 </intro>
12260
12261 <event label="Single Step"
12262 id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
12263 <description>
12264 Single step events allow the agent to trace thread execution
12265 at the finest granularity allowed by the VM. A single step event is
12266 generated whenever a thread reaches a new location.
12267 Typically, single step events represent the completion of one VM
12268 instruction as defined in <vmspec/>. However, some implementations
12269 may define locations differently. In any case the
12270 <code>method</code> and <code>location</code>
12271 parameters uniquely identify the current location and allow
12272 the mapping to source file and line number when that information is
12273 available.
12274 <p/>
12275 No single step events are generated from within native methods.
12276 </description>
12277 <origin>jvmdi</origin>
12278 <capabilities>
12279 <required id="can_generate_single_step_events"></required>
12280 </capabilities>
12281 <parameters>
12282 <param id="jni_env">
12283 <outptr>
12284 <struct>JNIEnv</struct>
12285 </outptr>
12286 <description>
12287 The JNI environment of the event (current) thread
12288 </description>
12289 </param>
12290 <param id="thread">
12291 <jthread/>
12292 <description>
12293 Thread about to execution a new instruction
12294 </description>
12295 </param>
12296 <param id="klass">
12297 <jclass method="method"/>
12298 <description>
12299 Class of the method about to execute a new instruction
12300 </description>
12301 </param>
12302 <param id="method">
12303 <jmethodID class="klass"/>
12304 <description>
12305 Method about to execute a new instruction
12306 </description>
12307 </param>
12308 <param id="location">
12309 <jlocation/>
12310 <description>
12311 Location of the new instruction
12312 </description>
12313 </param>
12314 </parameters>
12315 </event>
12316
12317 <event label="Breakpoint"
12318 id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
12319 <description>
12320 Breakpoint events are generated whenever a thread reaches a location
12321 designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
12322 The <code>method</code> and <code>location</code>
12323 parameters uniquely identify the current location and allow
12324 the mapping to source file and line number when that information is
12325 available.
12326 </description>
12327 <origin>jvmdi</origin>
12328 <capabilities>
12329 <required id="can_generate_breakpoint_events"></required>
12330 </capabilities>
12331 <parameters>
12332 <param id="jni_env">
12333 <outptr>
12334 <struct>JNIEnv</struct>
12335 </outptr>
12336 <description>
12337 The JNI environment of the event (current) thread.
12338 </description>
12339 </param>
12340 <param id="thread">
12341 <jthread/>
12342 <description>
12343 Thread that hit the breakpoint
12344 </description>
12345 </param>
12346 <param id="klass">
12347 <jclass method="method"/>
12348 <description>
12349 Class of the method that hit the breakpoint
12350 </description>
12351 </param>
12352 <param id="method">
12353 <jmethodID class="klass"/>
12354 <description>
12355 Method that hit the breakpoint
12356 </description>
12357 </param>
12358 <param id="location">
12359 <jlocation/>
12360 <description>
12361 location of the breakpoint
12362 </description>
12363 </param>
12364 </parameters>
12365 </event>
12366
12367 <event label="Field Access"
12368 id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
12369 <description>
12370 Field access events are generated whenever a thread accesses
12371 a field that was designated as a watchpoint
12372 with <functionlink id="SetFieldAccessWatch"></functionlink>.
12373 The <code>method</code> and <code>location</code>
12374 parameters uniquely identify the current location and allow
12375 the mapping to source file and line number when that information is
12376 available.
12377 </description>
12378 <origin>jvmdi</origin>
12379 <capabilities>
12380 <required id="can_generate_field_access_events"></required>
12381 </capabilities>
12382 <parameters>
12383 <param id="jni_env">
12384 <outptr>
12385 <struct>JNIEnv</struct>
12386 </outptr>
12387 <description>
12388 The JNI environment of the event (current) thread
12389 </description>
12390 </param>
12391 <param id="thread">
12392 <jthread/>
12393 <description>
12394 Thread accessing the field
12395 </description>
12396 </param>
12397 <param id="klass">
12398 <jclass method="method"/>
12399 <description>
12400 Class of the method where the access is occurring
12401 </description>
12402 </param>
12403 <param id="method">
12404 <jmethodID class="klass"/>
12405 <description>
12406 Method where the access is occurring
12407 </description>
12408 </param>
12409 <param id="location">
12410 <jlocation/>
12411 <description>
12412 Location where the access is occurring
12413 </description>
12414 </param>
12415 <param id="field_klass">
12416 <jclass field="field"/>
12417 <description>
12418 Class of the field being accessed
12419 </description>
12420 </param>
12421 <param id="object">
12422 <jobject/>
12423 <description>
12424 Object with the field being accessed if the field is an
12425 instance field; <code>NULL</code> otherwise
12426 </description>
12427 </param>
12428 <param id="field">
12429 <jfieldID class="field_klass"/>
12430 <description>
12431 Field being accessed
12432 </description>
12433 </param>
12434 </parameters>
12435 </event>
12436
12437 <event label="Field Modification"
12438 id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
12439 <description>
12440 Field modification events are generated whenever a thread modifies
12441 a field that was designated as a watchpoint
12442 with <functionlink id="SetFieldModificationWatch"></functionlink>.
12443 The <code>method</code> and <code>location</code>
12444 parameters uniquely identify the current location and allow
12445 the mapping to source file and line number when that information is
12446 available.
12447 </description>
12448 <origin>jvmdi</origin>
12449 <capabilities>
12450 <required id="can_generate_field_modification_events"></required>
12451 </capabilities>
12452 <parameters>
12453 <param id="jni_env">
12454 <outptr>
12455 <struct>JNIEnv</struct>
12456 </outptr>
12457 <description>
12458 The JNI environment of the event (current) thread
12459 </description>
12460 </param>
12461 <param id="thread">
12462 <jthread/>
12463 <description>
12464 Thread modifying the field
12465 </description>
12466 </param>
12467 <param id="klass">
12468 <jclass method="method"/>
12469 <description>
12470 Class of the method where the modification is occurring
12471 </description>
12472 </param>
12473 <param id="method">
12474 <jmethodID class="klass"/>
12475 <description>
12476 Method where the modification is occurring
12477 </description>
12478 </param>
12479 <param id="location">
12480 <jlocation/>
12481 <description>
12482 Location where the modification is occurring
12483 </description>
12484 </param>
12485 <param id="field_klass">
12486 <jclass field="field"/>
12487 <description>
12488 Class of the field being modified
12489 </description>
12490 </param>
12491 <param id="object">
12492 <jobject/>
12493 <description>
12494 Object with the field being modified if the field is an
12495 instance field; <code>NULL</code> otherwise
12496 </description>
12497 </param>
12498 <param id="field">
12499 <jfieldID class="field_klass"/>
12500 <description>
12501 Field being modified
12502 </description>
12503 </param>
12504 <param id="signature_type">
12505 <char/>
12506 <description>
12507 Signature type of the new value
12508 </description>
12509 </param>
12510 <param id="new_value">
12511 <jvalue/>
12512 <description>
12513 The new value
12514 </description>
12515 </param>
12516 </parameters>
12517 </event>
12518
12519 <event label="Frame Pop"
12520 id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
12521 <description>
12522 Frame pop events are generated upon exit from a single method
12523 in a single frame as specified
12524 in a call to <functionlink id="NotifyFramePop"></functionlink>.
12525 This is true whether termination is caused by
12526 executing its return instruction
12527 or by throwing an exception to its caller
12528 (see <paramlink id="was_popped_by_exception"></paramlink>).
12529 However, frame pops caused by the <functionlink id="PopFrame"/>
12530 function are not reported.
12531 <p/>
12532 The location reported by <functionlink id="GetFrameLocation"></functionlink>
12533 for the depth 0 identifies the executable location in the returning method,
12534 immediately prior to the return.
12535 </description>
12536 <origin>jvmdi</origin>
12537 <capabilities>
12538 <required id="can_generate_frame_pop_events"></required>
12539 </capabilities>
12540 <parameters>
12541 <param id="jni_env">
12542 <outptr>
12543 <struct>JNIEnv</struct>
12544 </outptr>
12545 <description>
12546 The JNI environment of the event (current) thread
12547 </description>
12548 </param>
12549 <param id="thread">
12550 <jthread/>
12551 <description>
12552 Thread that is popping the frame
12553 </description>
12554 </param>
12555 <param id="klass">
12556 <jclass method="method"/>
12557 <description>
12558 Class of the method being popped
12559 </description>
12560 </param>
12561 <param id="method">
12562 <jmethodID class="klass"/>
12563 <description>
12564 Method being popped
12565 </description>
12566 </param>
12567 <param id="was_popped_by_exception">
12568 <jboolean/>
12569 <description>
12570 True if frame was popped by a thrown exception.
12571 False if method exited through its return instruction.
12572 </description>
12573 </param>
12574 </parameters>
12575 </event>
12576
12577 <event label="Method Entry"
12578 id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
12579 <description>
12580 Method entry events are generated upon entry of Java
12581 programming language methods (including native methods).
12582 <p/>
12583 The location reported by <functionlink id="GetFrameLocation"></functionlink>
12584 for the depth 0 identifies the initial executable location in the method.
12585 <p/>
12586 Enabling method
12587 entry or exit events will significantly degrade performance on many platforms and is thus
12588 not advised for performance critical usage (such as profiling).
12589 <internallink id="bci">Bytecode instrumentation</internallink> should be
12590 used in these cases.
12591 </description>
12592 <origin>jvmdi</origin>
12593 <capabilities>
12594 <required id="can_generate_method_entry_events"></required>
12595 </capabilities>
12596 <parameters>
12597 <param id="jni_env">
12598 <outptr>
12599 <struct>JNIEnv</struct>
12600 </outptr>
12601 <description>
12602 The JNI environment of the event (current) thread
12603 </description>
12604 </param>
12605 <param id="thread">
12606 <jthread/>
12607 <description>
12608 Thread entering the method
12609 </description>
12610 </param>
12611 <param id="klass">
12612 <jclass method="method"/>
12613 <description>
12614 Class of the method being entered
12615 </description>
12616 </param>
12617 <param id="method">
12618 <jmethodID class="klass"/>
12619 <description>
12620 Method being entered
12621 </description>
12622 </param>
12623 </parameters>
12624 </event>
12625
12626 <event label="Method Exit"
12627 id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
12628 <description>
12629 Method exit events are generated upon exit from Java
12630 programming language methods (including native methods).
12631 This is true whether termination is caused by
12632 executing its return instruction
12633 or by throwing an exception to its caller
12634 (see <paramlink id="was_popped_by_exception"></paramlink>).
12635 <p/>
12636 The location reported by <functionlink id="GetFrameLocation"></functionlink>
12637 for the depth 0 identifies the executable location in the returning method
12638 immediately prior to the return.
12639 <p/>
12640 Enabling method
12641 entry or exit events will significantly degrade performance on many platforms and is thus
12642 not advised for performance critical usage (such as profiling).
12643 <internallink id="bci">Bytecode instrumentation</internallink> should be
12644 used in these cases.
12645 </description>
12646 <origin>jvmdi</origin>
12647 <capabilities>
12648 <required id="can_generate_method_exit_events"></required>
12649 </capabilities>
12650 <parameters>
12651 <param id="jni_env">
12652 <outptr>
12653 <struct>JNIEnv</struct>
12654 </outptr>
12655 <description>
12656 The JNI environment of the event (current) thread
12657 </description>
12658 </param>
12659 <param id="thread">
12660 <jthread/>
12661 <description>
12662 Thread exiting the method
12663 </description>
12664 </param>
12665 <param id="klass">
12666 <jclass method="method"/>
12667 <description>
12668 Class of the method being exited
12669 </description>
12670 </param>
12671 <param id="method">
12672 <jmethodID class="klass"/>
12673 <description>
12674 Method being exited
12675 </description>
12676 </param>
12677 <param id="was_popped_by_exception">
12678 <jboolean/>
12679 <description>
12680 True if frame was popped by a thrown exception.
12681 False if method exited through its return instruction.
12682 </description>
12683 </param>
12684 <param id="return_value">
12685 <jvalue/>
12686 <description>
12687 The return value of the method being exited.
12688 Undefined and should not be used if
12689 <paramlink id="was_popped_by_exception"></paramlink>
12690 is true.
12691 </description>
12692 </param>
12693 </parameters>
12694 </event>
12695
12696 <event label="Native Method Bind" phase="any"
12697 id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
12698 <description>
12699 A Native Method Bind event is sent when a VM binds a
12700 Java programming language native method
12701 to the address of a function that implements the native method.
12702 This will occur when the native method is called for the first time
12703 and also occurs when the JNI function <code>RegisterNatives</code> is called.
12704 This event allows the bind to be redirected to an agent-specified
12705 proxy function.
12706 This event is not sent when the native method is unbound.
12707 Typically, this proxy function will need to be specific to a
12708 particular method or, to handle the general case, automatically
12709 generated assembly code, since after instrumentation code is
12710 executed the function at the original binding
12711 address will usually be invoked.
12712 The original binding can be restored or the redirection changed
12713 by use of the JNI function <code>RegisterNatives</code>.
12714 Some events may be sent during the primordial phase, JNI and
12715 most of <jvmti/> cannot be used at this time but the method and
12716 address can be saved for use later.
12717 </description>
12718 <origin>new</origin>
12719 <capabilities>
12720 <required id="can_generate_native_method_bind_events"></required>
12721 </capabilities>
12722 <parameters>
12723 <param id="jni_env">
12724 <outptr>
12725 <struct>JNIEnv</struct>
12726 </outptr>
12727 <description>
12728 The JNI environment of the event (current) thread
12729 Will be <code>NULL</code> if sent during the primordial
12730 <functionlink id="GetPhase">phase</functionlink>.
12731 </description>
12732 </param>
12733 <param id="thread">
12734 <jthread/>
12735 <description>
12736 Thread requesting the bind
12737 </description>
12738 </param>
12739 <param id="klass">
12740 <jclass method="method"/>
12741 <description>
12742 Class of the method being bound
12743 </description>
12744 </param>
12745 <param id="method">
12746 <jmethodID class="klass"/>
12747 <description>
12748 Native method being bound
12749 </description>
12750 </param>
12751 <param id="address">
12752 <outptr><void/></outptr>
12753 <description>
12754 The address the VM is about to bind to--that is, the
12755 address of the implementation of the native method
12756 </description>
12757 </param>
12758 <param id="new_address_ptr">
12759 <agentbuf><void/></agentbuf>
12760 <description>
12761 if the referenced address is changed (that is, if
12762 <code>*new_address_ptr</code> is set), the binding
12763 will instead be made to the supplied address.
12764 </description>
12765 </param>
12766 </parameters>
12767 </event>
12768
12769 <event label="Exception"
12770 id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
12771 <description>
12772 Exception events are generated whenever an exception is first detected
12773 in a Java programming language method.
12774 Where "exception" means any <code>java.lang.Throwable</code>.
12775 The exception may have been thrown by a Java programming language or native
12776 method, but in the case of native methods, the event is not generated
12777 until the exception is first seen by a Java programming language method. If an exception is
12778 set and cleared in a native method (and thus is never visible to Java programming language code),
12779 no exception event is generated.
12780 <p/>
12781 The <code>method</code> and <code>location</code>
12782 parameters uniquely identify the current location
12783 (where the exception was detected) and allow
12784 the mapping to source file and line number when that information is
12785 available. The <code>exception</code> field identifies the thrown
12786 exception object. The <code>catch_method</code>
12787 and <code>catch_location</code> identify the location of the catch clause,
12788 if any, that handles the thrown exception. If there is no such catch clause,
12789 each field is set to 0. There is no guarantee that the thread will ever
12790 reach this catch clause. If there are native methods on the call stack
12791 between the throw location and the catch clause, the exception may
12792 be reset by one of those native methods.
12793 Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12794 et al. set to 0) may in fact be caught by native code.
12795 Agents can check for these occurrences by monitoring
12796 <eventlink id="ExceptionCatch"></eventlink> events.
12797 Note that finally clauses are implemented as catch and re-throw. Therefore they
12798 will be reported in the catch location.
12799 </description>
12800 <origin>jvmdi</origin>
12801 <capabilities>
12802 <required id="can_generate_exception_events"></required>
12803 </capabilities>
12804 <parameters>
12805 <param id="jni_env">
12806 <outptr>
12807 <struct>JNIEnv</struct>
12808 </outptr>
12809 <description>
12810 The JNI environment of the event (current) thread
12811 </description>
12812 </param>
12813 <param id="thread">
12814 <jthread/>
12815 <description>
12816 Thread generating the exception
12817 </description>
12818 </param>
12819 <param id="klass">
12820 <jclass method="method"/>
12821 <description>
12822 Class generating the exception
12823 </description>
12824 </param>
12825 <param id="method">
12826 <jmethodID class="klass"/>
12827 <description>
12828 Method generating the exception
12829 </description>
12830 </param>
12831 <param id="location">
12832 <jlocation/>
12833 <description>
12834 Location where exception occurred
12835 </description>
12836 </param>
12837 <param id="exception">
12838 <jobject/>
12839 <description>
12840 The exception being thrown
12841 </description>
12842 </param>
12843 <param id="catch_klass">
12844 <jclass method="catch_method"/>
12845 <description>
12846 Class that will catch the exception, or <code>NULL</code> if no known catch
12847 </description>
12848 </param>
12849 <param id="catch_method">
12850 <jmethodID class="catch_klass"/>
12851 <description>
12852 Method that will catch the exception, or <code>NULL</code> if no known catch
12853 </description>
12854 </param>
12855 <param id="catch_location">
12856 <jlocation/>
12857 <description>
12858 location which will catch the exception or zero if no known catch
12859 </description>
12860 </param>
12861 </parameters>
12862 </event>
12863
12864 <event label="Exception Catch"
12865 id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12866 <description>
12867 Exception catch events are generated whenever a thrown exception is caught.
12868 Where "exception" means any <code>java.lang.Throwable</code>.
12869 If the exception is caught in a Java programming language method, the event is generated
12870 when the catch clause is reached. If the exception is caught in a native
12871 method, the event is generated as soon as control is returned to a Java programming language
12872 method. Exception catch events are generated for any exception for which
12873 a throw was detected in a Java programming language method.
12874 Note that finally clauses are implemented as catch and re-throw. Therefore they
12875 will generate exception catch events.
12876 <p/>
12877 The <code>method</code> and <code>location</code>
12878 parameters uniquely identify the current location
12879 and allow the mapping to source file and line number when that information is
12880 available. For exceptions caught in a Java programming language method, the
12881 <code>exception</code> object identifies the exception object. Exceptions
12882 caught in native methods are not necessarily available by the time the
12883 exception catch is reported, so the <code>exception</code> field is set
12884 to <code>NULL</code>.
12885 </description>
12886 <origin>jvmdi</origin>
12887 <capabilities>
12888 <required id="can_generate_exception_events"></required>
12889 </capabilities>
12890 <parameters>
12891 <param id="jni_env">
12892 <outptr>
12893 <struct>JNIEnv</struct>
12894 </outptr>
12895 <description>
12896 The JNI environment of the event (current) thread
12897 </description>
12898 </param>
12899 <param id="thread">
12900 <jthread/>
12901 <description>
12902 Thread catching the exception
12903 </description>
12904 </param>
12905 <param id="klass">
12906 <jclass method="method"/>
12907 <description>
12908 Class catching the exception
12909 </description>
12910 </param>
12911 <param id="method">
12912 <jmethodID class="klass"/>
12913 <description>
12914 Method catching the exception
12915 </description>
12916 </param>
12917 <param id="location">
12918 <jlocation/>
12919 <description>
12920 Location where exception is being caught
12921 </description>
12922 </param>
12923 <param id="exception">
12924 <jobject/>
12925 <description>
12926 Exception being caught
12927 </description>
12928 </param>
12929 </parameters>
12930 </event>
12931
12932 <event label="Thread Start"
12933 id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12934 <description>
12935 A thread start event is generated by a new thread before its initial
12936 method executes.
12937 <p/>
12938 This event is generated by platform threads. It is also generated by
12939 virtual threads when the capability
12940 <internallink id="jvmtiCapabilities.can_support_virtual_threads">
12941 <code>can_support_virtual_threads</code></internallink> is not enabled.
12942 Agents without support for virtual threads that enable this event will
12943 therefore be notified by all newly started threads.
12944 <p/>
12945 If the capability <code>can_support_virtual_threads</code> is enabled then
12946 this event is not generated by virtual threads. Agents with support for
12947 virtual threads can enable <eventlink id="VirtualThreadStart"></eventlink>
12948 to be notified by newly started virtual threads.
12949 <p/>
12950 A platform thread may be listed in the array returned by
12951 <functionlink id="GetAllThreads"></functionlink>
12952 before its thread start event is generated.
12953 It is possible for other events to be generated
12954 on a thread before its thread start event.
12955 <p/>
12956 The event is sent on the newly started <paramlink id="thread"></paramlink>.
12957 </description>
12958 <origin>jvmdi</origin>
12959 <capabilities>
12960 </capabilities>
12961 <parameters>
12962 <param id="jni_env">
12963 <outptr>
12964 <struct>JNIEnv</struct>
12965 </outptr>
12966 <description>
12967 The JNI environment of the event (current) thread.
12968 </description>
12969 </param>
12970 <param id="thread">
12971 <jthread/>
12972 <description>
12973 Thread starting
12974 </description>
12975 </param>
12976 </parameters>
12977 </event>
12978
12979 <event label="Thread End"
12980 id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
12981 <description>
12982 A thread end event is generated by a terminating thread after its
12983 initial method has finished execution.
12984 <p/>
12985 This event is generated by platform threads. It is also generated by
12986 virtual threads when the capability
12987 <internallink id="jvmtiCapabilities.can_support_virtual_threads">
12988 <code>can_support_virtual_threads</code></internallink> is not enabled.
12989 Agents without support for virtual threads that enable this event for
12990 all threads will therefore be notified by all terminating threads.
12991 <p/>
12992 If the capability <code>can_support_virtual_threads</code> is enabled then
12993 this event is not generated by virtual threads. Agents with support for
12994 virtual threads can enable <eventlink id="VirtualThreadEnd"></eventlink>
12995 to be notified by terminating virtual threads.
12996 <p/>
12997 A platform thread may be listed in the array returned by
12998 <functionlink id="GetAllThreads"></functionlink>
12999 after its thread end event is generated.
13000 No events are generated on a thread
13001 after its thread end event.
13002 <p/>
13003 The event is sent on the terminating <paramlink id="thread"></paramlink>.
13004 </description>
13005 <origin>jvmdi</origin>
13006 <capabilities>
13007 </capabilities>
13008 <parameters>
13009 <param id="jni_env">
13010 <outptr>
13011 <struct>JNIEnv</struct>
13012 </outptr>
13013 <description>
13014 The JNI environment of the event (current) thread.
13015 </description>
13016 </param>
13017 <param id="thread">
13018 <jthread/>
13019 <description>
13020 Thread ending
13021 </description>
13022 </param>
13023 </parameters>
13024 </event>
13025
13026 <event label="Virtual Thread Start"
13027 id="VirtualThreadStart" const="JVMTI_EVENT_VIRTUAL_THREAD_START" filtered="thread" num="87" phase="start" since="21">
13028 <description>
13029 A virtual thread start event is generated before its initial method executes.
13030 <p/>
13031 The event is sent on the newly started <paramlink id="virtual_thread"></paramlink>.
13032 </description>
13033 <origin>new</origin>
13034 <capabilities>
13035 <required id="can_support_virtual_threads">Can support virtual threads</required>
13036 </capabilities>
13037 <parameters>
13038 <param id="jni_env">
13039 <outptr>
13040 <struct>JNIEnv</struct>
13041 </outptr>
13042 <description>
13043 The JNI environment of the event (current) thread.
13044 </description>
13045 </param>
13046 <param id="virtual_thread">
13047 <jthread/>
13048 <description>
13049 Virtual thread started for execution.
13050 </description>
13051 </param>
13052 </parameters>
13053 </event>
13054
13055 <event label="Virtual Thread End"
13056 id="VirtualThreadEnd" const="JVMTI_EVENT_VIRTUAL_THREAD_END" filtered="thread" num="88" phase="start" since="21">
13057 <description>
13058 A virtual thread end event is generated after its initial method has finished execution.
13059 <p/>
13060 The event is sent on the terminating <paramlink id="virtual_thread"></paramlink>.
13061 </description>
13062 <origin>new</origin>
13063 <capabilities>
13064 <required id="can_support_virtual_threads">Can support virtual threads</required>
13065 </capabilities>
13066 <parameters>
13067 <param id="jni_env">
13068 <outptr>
13069 <struct>JNIEnv</struct>
13070 </outptr>
13071 <description>
13072 The JNI environment of the event (current) thread.
13073 </description>
13074 </param>
13075 <param id="virtual_thread">
13076 <jthread/>
13077 <description>
13078 Virtual thread being ended.
13079 </description>
13080 </param>
13081 </parameters>
13082 </event>
13083
13084 <elide>
13085 <event label="Virtual Thread Mount"
13086 id="VirtualThreadMount" const="JVMTI_EVENT_VIRTUAL_THREAD_MOUNT" filtered="thread" num="89" phase="start" since="99">
13087 <description>
13088 A virtual thread mount event is generated before its method continue to execute on the mounted thread.
13089 <p/>
13090 The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is mounted to.
13091 </description>
13092 <origin>new</origin>
13093 <capabilities>
13094 <required id="can_support_virtual_threads">Can support virtual threads</required>
13095 </capabilities>
13096 <parameters>
13097 <param id="jni_env">
13098 <outptr>
13099 <struct>JNIEnv</struct>
13100 </outptr>
13101 <description>
13102 The JNI environment of the event (current) thread.
13103 </description>
13104 </param>
13105 <param id="virtual_thread">
13106 <jthread/>
13107 <description>
13108 Virtual thread that is mounted.
13109 </description>
13110 </param>
13111 </parameters>
13112 </event>
13113 </elide>
13114
13115 <elide>
13116 <event label="Virtual Thread Unmount"
13117 id="VirtualThreadUnmount" const="JVMTI_EVENT_VIRTUAL_THREAD_UNMOUNT" filtered="thread" num="90" phase="start" since="99">
13118 <description>
13119 A virtual thread unmount event is generated when the virtual thread is about to be unmounted from the carrier thread.
13120 <p/>
13121 The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is unmounted from.
13122 </description>
13123 <origin>new</origin>
13124 <capabilities>
13125 <required id="can_support_virtual_threads">Can support virtual threads</required>
13126 </capabilities>
13127 <parameters>
13128 <param id="jni_env">
13129 <outptr>
13130 <struct>JNIEnv</struct>
13131 </outptr>
13132 <description>
13133 The JNI environment of the event (current) thread.
13134 </description>
13135 </param>
13136 <param id="virtual_thread">
13137 <jthread/>
13138 <description>
13139 Virtual thread that is unmounted.
13140 </description>
13141 </param>
13142 </parameters>
13143 </event>
13144 </elide>
13145
13146 <event label="Class Load"
13147 id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
13148 <description>
13149 A class load event is generated
13150 <functionlink id="GetLoadedClasses">when a class or interface is created.</functionlink>.
13151 <p/>
13152 Array class creation does not generate a class load event.
13153 The creation of a primitive class (for example, java.lang.Integer.TYPE)
13154 does not generate a class load event.
13155 <p/>
13156 The order of class load events generated by a particular thread is guaranteed
13157 to match the order of class loading within that thread.
13158 <p/>
13159 This event is sent at an early stage in loading the class. As
13160 a result the class should be used carefully. Note, for example,
13161 that methods and fields are not yet loaded, so queries for methods,
13162 fields, subclasses, and so on will not give correct results.
13163 See "Loading of Classes and Interfaces" in the <i>Java Language
13164 Specification</i>. For most
13165 purposes the <eventlink id="ClassPrepare"></eventlink> event will
13166 be more useful.
13167 </description>
13168 <origin>jvmdi</origin>
13169 <capabilities>
13170 </capabilities>
13171 <parameters>
13172 <param id="jni_env">
13173 <outptr>
13174 <struct>JNIEnv</struct>
13175 </outptr>
13176 <description>
13177 The JNI environment of the event (current) thread
13178 </description>
13179 </param>
13180 <param id="thread">
13181 <jthread/>
13182 <description>
13183 Thread loading the class
13184 </description>
13185 </param>
13186 <param id="klass">
13187 <jclass/>
13188 <description>
13189 Class being loaded
13190 </description>
13191 </param>
13192 </parameters>
13193 </event>
13194
13195 <elide>
13196 <event label="Class Unload"
13197 id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
13198 <description>
13199 A class unload event is generated when the class is about to be unloaded.
13200 Class unload events take place during garbage collection and must be
13201 handled extremely carefully. The garbage collector holds many locks
13202 and has suspended all other threads, so the event handler cannot depend
13203 on the ability to acquire any locks. The class unload event handler should
13204 do as little as possible, perhaps by queuing information to be processed
13205 later. In particular, the <code>jclass</code> should be used only in
13206 the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
13207 <ul>
13208 <li><functionlink id="GetClassSignature"></functionlink></li>
13209 <li><functionlink id="GetSourceFileName"></functionlink></li>
13210 <li><functionlink id="IsInterface"></functionlink></li>
13211 <li><functionlink id="IsArrayClass"></functionlink></li>
13212 </ul>
13213 </description>
13214 <origin>jvmdi</origin>
13215 <capabilities>
13216 </capabilities>
13217 <parameters>
13218 <param id="jni_env">
13219 <outptr>
13220 <struct>JNIEnv</struct>
13221 </outptr>
13222 <description>
13223 The JNI environment of the event (current) thread
13224 </description>
13225 </param>
13226 <param id="thread">
13227 <jthread/>
13228 <description>
13229 Thread generating the class unload
13230 </description>
13231 </param>
13232 <param id="klass">
13233 <jclass/>
13234 <description>
13235 Class being unloaded
13236 </description>
13237 </param>
13238 </parameters>
13239 </event>
13240 </elide>
13241
13242 <event label="Class Prepare"
13243 id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
13244 <description>
13245 A class prepare event is generated when class preparation is complete.
13246 At this point, class fields, methods, and implemented interfaces are
13247 available, and no code from the class has been executed. Since array
13248 classes never have fields or methods, class prepare events are not
13249 generated for them. Class prepare events are not generated for
13250 primitive classes (for example, <code>java.lang.Integer.TYPE</code>).
13251 </description>
13252 <origin>jvmdi</origin>
13253 <capabilities>
13254 </capabilities>
13255 <parameters>
13256 <param id="jni_env">
13257 <outptr>
13258 <struct>JNIEnv</struct>
13259 </outptr>
13260 <description>
13261 The JNI environment of the event (current) thread
13262 </description>
13263 </param>
13264 <param id="thread">
13265 <jthread/>
13266 <description>
13267 Thread generating the class prepare
13268 </description>
13269 </param>
13270 <param id="klass">
13271 <jclass/>
13272 <description>
13273 Class being prepared
13274 </description>
13275 </param>
13276 </parameters>
13277 </event>
13278
13279 <event label="Class File Load Hook" phase="any"
13280 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
13281 <description>
13282 This event is sent when the VM obtains class file data,
13283 but before it constructs
13284 the in-memory representation for that class.
13285 This event is also sent when the class is being modified by the
13286 <functionlink id="RetransformClasses"/> function or
13287 the <functionlink id="RedefineClasses"/> function,
13288 called in any <jvmti/> environment.
13289 The agent can instrument
13290 the existing class file data sent by the VM to include profiling/debugging hooks.
13291 See the description of
13292 <internallink id="bci">bytecode instrumentation</internallink>
13293 for usage information.
13294 <p/>
13295 When the capabilities
13296 <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
13297 <code>can_generate_early_class_hook_events</code></internallink> and
13298 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
13299 <code>can_generate_all_class_hook_events</code></internallink>
13300 are enabled then this event may be sent in the primordial phase.
13301 Otherwise, this event may be sent before the VM is initialized (the start
13302 <functionlink id="GetPhase">phase</functionlink>).
13303 Some classes might not be compatible
13304 with the function (eg. ROMized classes or implementation defined classes) and this event will
13305 not be generated for these classes.
13306 <p/>
13307 The agent must allocate the space for the modified
13308 class file data buffer
13309 using the memory allocation function
13310 <functionlink id="Allocate"></functionlink> because the
13311 VM is responsible for freeing the new class file data buffer
13312 using <functionlink id="Deallocate"></functionlink>.
13313 <p/>
13314 If the agent wishes to modify the class file, it must set
13315 <code>new_class_data</code> to point
13316 to the newly instrumented class file data buffer and set
13317 <code>new_class_data_len</code> to the length of that
13318 buffer before returning
13319 from this call. If no modification is desired, the agent simply
13320 does not set <code>new_class_data</code>. If multiple agents
13321 have enabled this event the results are chained. That is, if
13322 <code>new_class_data</code> has been set, it becomes the
13323 <code>class_data</code> for the next agent.
13324 <p/>
13325 When handling a class load in the live phase, then the
13326 <functionlink id="GetNamedModule"></functionlink>
13327 function can be used to map class loader and a package name to a module.
13328 When a class is being redefined or retransformed then
13329 <code>class_being_redefined</code> is non <code>NULL</code> and so
13330 the JNI <code>GetModule</code> function can also be used
13331 to obtain the Module.
13332 <p/>
13333 The order that this event is sent to each environment differs
13334 from other events.
13335 This event is sent to environments in the following order:
13336 <ul>
13337 <li><fieldlink id="can_retransform_classes"
13338 struct="jvmtiCapabilities">retransformation
13339 incapable</fieldlink>
13340 environments, in the
13341 order in which they were created
13342 </li>
13343 <li><fieldlink id="can_retransform_classes"
13344 struct="jvmtiCapabilities">retransformation
13345 capable</fieldlink>
13346 environments, in the
13347 order in which they were created
13348 </li>
13349 </ul>
13350 When triggered by <functionlink id="RetransformClasses"/>,
13351 this event is sent only to <fieldlink id="can_retransform_classes"
13352 struct="jvmtiCapabilities">retransformation
13353 capable</fieldlink>
13354 environments.
13355 </description>
13356 <origin>jvmpi</origin>
13357 <capabilities>
13358 <capability id="can_generate_all_class_hook_events"></capability>
13359 <capability id="can_generate_early_class_hook_events"></capability>
13360 </capabilities>
13361 <parameters>
13362 <param id="jni_env">
13363 <outptr>
13364 <struct>JNIEnv</struct>
13365 </outptr>
13366 <description>
13367 The JNI environment of the event (current) thread.
13368 </description>
13369 </param>
13370 <param id="class_being_redefined">
13371 <jclass/>
13372 <description>
13373 The class being
13374 <functionlink id="RedefineClasses">redefined</functionlink> or
13375 <functionlink id="RetransformClasses">retransformed</functionlink>.
13376 <code>NULL</code> if sent by class load.
13377 </description>
13378 </param>
13379 <param id="loader">
13380 <jobject/>
13381 <description>
13382 The class loader loading the class.
13383 <code>NULL</code> if the bootstrap class loader.
13384 </description>
13385 </param>
13386 <param id="name">
13387 <vmbuf><char/></vmbuf>
13388 <description>
13389 Name of class being loaded as a VM internal qualified name
13390 (for example, "java/util/List"), encoded as a
13391 <internallink id="mUTF">modified UTF-8</internallink> string.
13392 Note: if the class is defined with a <code>NULL</code> name or
13393 without a name specified, <code>name</code> will be <code>NULL</code>.
13394 </description>
13395 </param>
13396 <param id="protection_domain">
13397 <jobject/>
13398 <description>
13399 The <code>ProtectionDomain</code> of the class.
13400 </description>
13401 </param>
13402 <param id="class_data_len">
13403 <jint/>
13404 <description>
13405 Length of current class file data buffer.
13406 </description>
13407 </param>
13408 <param id="class_data">
13409 <vmbuf><uchar/></vmbuf>
13410 <description>
13411 Pointer to the current class file data buffer.
13412 </description>
13413 </param>
13414 <param id="new_class_data_len">
13415 <outptr><jint/></outptr>
13416 <description>
13417 Pointer to the length of the new class file data buffer.
13418 </description>
13419 </param>
13420 <param id="new_class_data">
13421 <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
13422 <description>
13423 Pointer to the pointer to the instrumented class file data buffer.
13424 </description>
13425 </param>
13426 </parameters>
13427 </event>
13428
13429 <event label="VM Start Event"
13430 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
13431 <description>
13432 The VM start event signals the start of the VM.
13433 At this time JNI is live but the VM is not yet fully initialized.
13434 Once this event is generated, the agent is free to call any JNI function.
13435 This event signals the beginning of the start phase,
13436 <jvmti/> functions permitted in the start phase may be called.
13437 <p/>
13438 The timing of this event may depend on whether the agent has added the
13439 <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
13440 <code>can_generate_early_vmstart</code></internallink> capability or not.
13441 If the capability has been added then the VM posts the event as early
13442 as possible. The VM is capable of executing bytecode but it may not have
13443 initialized to the point where it can load classes in modules other than
13444 <code>java.base</code>, or even arbitrary classes in <code>java.base</code>.
13445 Agents that do load-time instrumentation in this
13446 phase must take great care when instrumenting code that potentially
13447 executes in this phase. Extreme care should also be taken with JNI
13448 <code>FindClass</code> as it may not be possible to load classes and attempts
13449 to do so may result in unpredictable behavior, maybe even stability issues
13450 on some VM implementations.
13451 If the capability has not been added then the VM delays posting this
13452 event until it is capable of loading classes in modules other than
13453 <code>java.base</code> or the VM has completed its initialization.
13454 Agents that create more than one JVM TI environment, where the
13455 capability is added to some but not all environments, may observe the
13456 start phase beginning earlier in the JVM TI environments that possess
13457 the capability.
13458 <p/>
13459 In the case of VM start-up failure, this event will not be sent.
13460 </description>
13461 <origin>jvmdi</origin>
13462 <capabilities>
13463 </capabilities>
13464 <parameters>
13465 <param id="jni_env">
13466 <outptr>
13467 <struct>JNIEnv</struct>
13468 </outptr>
13469 <description>
13470 The JNI environment of the event (current) thread.
13471 </description>
13472 </param>
13473 </parameters>
13474 </event>
13475
13476 <event label="VM Initialization Event"
13477 id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
13478 <description>
13479 The VM initialization event signals the completion of VM initialization. Once
13480 this event is generated, the agent is free to call any JNI or <jvmti/>
13481 function. The VM initialization event can be preceded by or can be concurrent
13482 with other events, but
13483 the preceding events should be handled carefully, if at all, because the
13484 VM has not completed its initialization. The thread start event for the
13485 main application thread is guaranteed not to occur until after the
13486 handler for the VM initialization event returns.
13487 <p/>
13488 In the case of VM start-up failure, this event will not be sent.
13489 </description>
13490 <origin>jvmdi</origin>
13491 <capabilities>
13492 </capabilities>
13493 <parameters>
13494 <param id="jni_env">
13495 <outptr>
13496 <struct>JNIEnv</struct>
13497 </outptr>
13498 <description>
13499 The JNI environment of the event (current) thread.
13500 </description>
13501 </param>
13502 <param id="thread">
13503 <jthread/>
13504 <description>
13505 The initial thread
13506 </description>
13507 </param>
13508 </parameters>
13509 </event>
13510
13511 <event label="VM Death Event"
13512 id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
13513 <description>
13514 The VM death event notifies the agent of the termination of the VM.
13515 No events will occur after the VMDeath event.
13516 <p/>
13517 In the case of VM start-up failure, this event will not be sent.
13518 Note that <internallink id="onunload">Agent_OnUnload</internallink>
13519 will still be called in these cases.
13520 </description>
13521 <origin>jvmdi</origin>
13522 <capabilities>
13523 </capabilities>
13524 <parameters>
13525 <param id="jni_env">
13526 <outptr>
13527 <struct>JNIEnv</struct>
13528 </outptr>
13529 <description>
13530 The JNI environment of the event (current) thread
13531 </description>
13532 </param>
13533 </parameters>
13534 </event>
13535
13536 <event label="Compiled Method Load" phase="start"
13537 id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
13538 <description>
13539 Sent when a method is compiled and loaded into memory by the VM.
13540 If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
13541 If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
13542 followed by a new <code>CompiledMethodLoad</code> event.
13543 Note that a single method may have multiple compiled forms, and that
13544 this event will be sent for each form.
13545 Note also that several methods may be inlined into a single
13546 address range, and that this event will be sent for each method.
13547 <p/>
13548 These events can be sent after their initial occurrence with
13549 <functionlink id="GenerateEvents"></functionlink>.
13550 </description>
13551 <origin>jvmpi</origin>
13552 <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
13553 <field id="start_address">
13554 <vmbuf><void/></vmbuf>
13555 <description>
13556 Starting native address of code corresponding to a location
13557 </description>
13558 </field>
13559 <field id="location">
13560 <jlocation/>
13561 <description>
13562 Corresponding location. See
13563 <functionlink id="GetJLocationFormat"></functionlink>
13564 for the meaning of location.
13565 </description>
13566 </field>
13567 </typedef>
13568 <capabilities>
13569 <required id="can_generate_compiled_method_load_events"></required>
13570 </capabilities>
13571 <parameters>
13572 <param id="klass">
13573 <jclass method="method"/>
13574 <description>
13575 Class of the method being compiled and loaded
13576 </description>
13577 </param>
13578 <param id="method">
13579 <jmethodID class="klass"/>
13580 <description>
13581 Method being compiled and loaded
13582 </description>
13583 </param>
13584 <param id="code_size">
13585 <jint/>
13586 <description>
13587 Size of compiled code
13588 </description>
13589 </param>
13590 <param id="code_addr">
13591 <vmbuf><void/></vmbuf>
13592 <description>
13593 Address where compiled method code is loaded
13594 </description>
13595 </param>
13596 <param id="map_length">
13597 <jint/>
13598 <description>
13599 Number of <typelink id="jvmtiAddrLocationMap"></typelink>
13600 entries in the address map.
13601 Zero if mapping information cannot be supplied.
13602 </description>
13603 </param>
13604 <param id="map">
13605 <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
13606 <description>
13607 Map from native addresses to location.
13608 The native address range of each entry is from
13609 <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
13610 to <code>start_address-1</code> of the next entry.
13611 <code>NULL</code> if mapping information cannot be supplied.
13612 </description>
13613 </param>
13614 <param id="compile_info">
13615 <vmbuf><void/></vmbuf>
13616 <description>
13617 VM-specific compilation information.
13618 The referenced compile information is managed by the VM
13619 and must not depend on the agent for collection.
13620 A VM implementation defines the content and lifetime
13621 of the information.
13622 </description>
13623 </param>
13624 </parameters>
13625 </event>
13626
13627 <event label="Compiled Method Unload" phase="start"
13628 id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
13629 <description>
13630 Sent when a compiled method is unloaded from memory.
13631 This event might not be sent on the thread which performed the unload.
13632 This event may be sent sometime after the unload occurs, but
13633 will be sent before the memory is reused
13634 by a newly generated compiled method. This event may be sent after
13635 the class is unloaded.
13636 </description>
13637 <origin>jvmpi</origin>
13638 <capabilities>
13639 <required id="can_generate_compiled_method_load_events"></required>
13640 </capabilities>
13641 <parameters>
13642 <param id="klass">
13643 <jclass method="method"/>
13644 <description>
13645 Class of the compiled method being unloaded.
13646 </description>
13647 </param>
13648 <param id="method">
13649 <jmethodID class="klass"/>
13650 <description>
13651 Compiled method being unloaded.
13652 For identification of the compiled method only -- the class
13653 may be unloaded and therefore the method should not be used
13654 as an argument to further JNI or <jvmti/> functions.
13655 </description>
13656 </param>
13657 <param id="code_addr">
13658 <vmbuf><void/></vmbuf>
13659 <description>
13660 Address where compiled method code was loaded.
13661 For identification of the compiled method only --
13662 the space may have been reclaimed.
13663 </description>
13664 </param>
13665 </parameters>
13666 </event>
13667
13668 <event label="Dynamic Code Generated" phase="any"
13669 id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
13670 <description>
13671 Sent when a component of the virtual machine is generated dynamically.
13672 This does not correspond to Java programming language code that is
13673 compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
13674 This is for native code--for example, an interpreter that is generated
13675 differently depending on command-line options.
13676 <p/>
13677 Note that this event has no controlling capability.
13678 If a VM cannot generate these events, it simply does not send any.
13679 <p/>
13680 These events can be sent after their initial occurrence with
13681 <functionlink id="GenerateEvents"></functionlink>.
13682 </description>
13683 <origin>jvmpi</origin>
13684 <capabilities>
13685 </capabilities>
13686 <parameters>
13687 <param id="name">
13688 <vmbuf><char/></vmbuf>
13689 <description>
13690 Name of the code, encoded as a
13691 <internallink id="mUTF">modified UTF-8</internallink> string.
13692 Intended for display to an end-user.
13693 The name might not be unique.
13694 </description>
13695 </param>
13696 <param id="address">
13697 <vmbuf><void/></vmbuf>
13698 <description>
13699 Native address of the code
13700 </description>
13701 </param>
13702 <param id="length">
13703 <jint/>
13704 <description>
13705 Length in bytes of the code
13706 </description>
13707 </param>
13708 </parameters>
13709 </event>
13710
13711 <event label="Data Dump Request"
13712 id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13713 <description>
13714 Sent by the VM to request the agent to dump its data. This
13715 is just a hint and the agent need not react to this event.
13716 This is useful for processing command-line signals from users. For
13717 example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Linux
13718 causes the VM to send this event to the agent.
13719 </description>
13720 <origin>jvmpi</origin>
13721 <capabilities>
13722 </capabilities>
13723 <parameters>
13724 </parameters>
13725 </event>
13726
13727 <event label="Monitor Contended Enter"
13728 id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13729 <description>
13730 Sent when a thread is attempting to enter a Java programming language
13731 monitor already acquired by another thread.
13732 </description>
13733 <origin>jvmpi</origin>
13734 <capabilities>
13735 <required id="can_generate_monitor_events"></required>
13736 </capabilities>
13737 <parameters>
13738 <param id="jni_env">
13739 <outptr>
13740 <struct>JNIEnv</struct>
13741 </outptr>
13742 <description>
13743 The JNI environment of the event (current) thread
13744 </description>
13745 </param>
13746 <param id="thread">
13747 <jthread/>
13748 <description>
13749 JNI local reference to the thread
13750 attempting to enter the monitor
13751 </description>
13752 </param>
13753 <param id="object">
13754 <jobject/>
13755 <description>
13756 JNI local reference to the monitor
13757 </description>
13758 </param>
13759 </parameters>
13760 </event>
13761
13762 <event label="Monitor Contended Entered"
13763 id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
13764 <description>
13765 Sent when a thread enters a Java programming language
13766 monitor after waiting for it to be released by another thread.
13767 </description>
13768 <origin>jvmpi</origin>
13769 <capabilities>
13770 <required id="can_generate_monitor_events"></required>
13771 </capabilities>
13772 <parameters>
13773 <param id="jni_env">
13774 <outptr>
13775 <struct>JNIEnv</struct>
13776 </outptr>
13777 <description>
13778 The JNI environment of the event (current) thread
13779 </description>
13780 </param>
13781 <param id="thread">
13782 <jthread/>
13783 <description>
13784 JNI local reference to the thread entering
13785 the monitor
13786 </description>
13787 </param>
13788 <param id="object">
13789 <jobject/>
13790 <description>
13791 JNI local reference to the monitor
13792 </description>
13793 </param>
13794 </parameters>
13795 </event>
13796
13797 <event label="Monitor Wait"
13798 id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
13799 <description>
13800 Sent when a thread is about to wait on an object.
13801 </description>
13802 <origin>jvmpi</origin>
13803 <capabilities>
13804 <required id="can_generate_monitor_events"></required>
13805 </capabilities>
13806 <parameters>
13807 <param id="jni_env">
13808 <outptr>
13809 <struct>JNIEnv</struct>
13810 </outptr>
13811 <description>
13812 The JNI environment of the event (current) thread
13813 </description>
13814 </param>
13815 <param id="thread">
13816 <jthread/>
13817 <description>
13818 JNI local reference to the thread about to wait
13819 </description>
13820 </param>
13821 <param id="object">
13822 <jobject/>
13823 <description>
13824 JNI local reference to the monitor
13825 </description>
13826 </param>
13827 <param id="timeout">
13828 <jlong/>
13829 <description>
13830 The number of milliseconds the thread will wait
13831 </description>
13832 </param>
13833 </parameters>
13834 </event>
13835
13836 <event label="Monitor Waited"
13837 id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
13838 <description>
13839 Sent when a thread finishes waiting on an object.
13840 </description>
13841 <origin>jvmpi</origin>
13842 <capabilities>
13843 <required id="can_generate_monitor_events"></required>
13844 </capabilities>
13845 <parameters>
13846 <param id="jni_env">
13847 <outptr>
13848 <struct>JNIEnv</struct>
13849 </outptr>
13850 <description>
13851 The JNI environment of the event (current) thread
13852 </description>
13853 </param>
13854 <param id="thread">
13855 <jthread/>
13856 <description>
13857 JNI local reference to the thread that was finished waiting
13858 </description>
13859 </param>
13860 <param id="object">
13861 <jobject/>
13862 <description>
13863 JNI local reference to the monitor.
13864 </description>
13865 </param>
13866 <param id="timed_out">
13867 <jboolean/>
13868 <description>
13869 True if the monitor timed out
13870 </description>
13871 </param>
13872 </parameters>
13873 </event>
13874
13875 <event label="Resource Exhausted"
13876 id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
13877 since="1.1">
13878 <description>
13879 Sent when a VM resource needed by a running application has been exhausted.
13880 Except as required by the optional capabilities, the set of resources
13881 which report exhaustion is implementation dependent.
13882 <p/>
13883 The following bit flags define the properties of the resource exhaustion:
13884 <constants id="jvmtiResourceExhaustionFlags"
13885 label="Resource Exhaustion Flags"
13886 kind="bits"
13887 since="1.1">
13888 <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
13889 After this event returns, the VM will throw a
13890 <code>java.lang.OutOfMemoryError</code>.
13891 </constant>
13892 <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
13893 The VM was unable to allocate memory from the <tm>Java</tm>
13894 platform <i>heap</i>.
13895 The <i>heap</i> is the runtime
13896 data area from which memory for all class instances and
13897 arrays are allocated.
13898 </constant>
13899 <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
13900 The VM was unable to create a thread.
13901 </constant>
13902 </constants>
13903 </description>
13904 <origin>new</origin>
13905 <capabilities>
13906 <capability id="can_generate_resource_exhaustion_heap_events">
13907 Can generate events when the VM is unable to allocate memory from the
13908 <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
13909 </capability>
13910 <capability id="can_generate_resource_exhaustion_threads_events">
13911 Can generate events when the VM is unable to
13912 <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
13913 a thread</internallink>.
13914 </capability>
13915 </capabilities>
13916 <parameters>
13917 <param id="jni_env">
13918 <outptr>
13919 <struct>JNIEnv</struct>
13920 </outptr>
13921 <description>
13922 The JNI environment of the event (current) thread
13923 </description>
13924 </param>
13925 <param id="flags">
13926 <jint/>
13927 <description>
13928 Flags defining the properties of the of resource exhaustion
13929 as specified by the
13930 <internallink id="jvmtiResourceExhaustionFlags">Resource
13931 Exhaustion Flags</internallink>.
13932 </description>
13933 </param>
13934 <param id="reserved">
13935 <vmbuf><void/></vmbuf>
13936 <description>
13937 Reserved.
13938 </description>
13939 </param>
13940 <param id="description">
13941 <vmbuf><char/></vmbuf>
13942 <description>
13943 Description of the resource exhaustion, encoded as a
13944 <internallink id="mUTF">modified UTF-8</internallink> string.
13945 </description>
13946 </param>
13947 </parameters>
13948 </event>
13949
13950 <event label="VM Object Allocation"
13951 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13952 <description>
13953 Sent when a method causes the virtual machine to directly allocate an
13954 Object visible to Java programming language code.
13955 Generally object allocation should be detected by instrumenting
13956 the bytecodes of allocating methods.
13957 Object allocation generated in native code by JNI function
13958 calls should be detected using
13959 <internallink id="jniIntercept">JNI function interception</internallink>.
13960 Some methods might not have associated bytecodes and are not
13961 native methods, they instead are executed directly by the
13962 VM. These methods should send this event.
13963 Virtual machines which are incapable of bytecode instrumentation
13964 for some or all of their methods can send this event.
13965
13966 Note that the <internallink
13967 id="SampledObjectAlloc">SampledObjectAlloc</internallink>
13968 event is triggered on all Java object allocations, including those
13969 caused by bytecode method execution, JNI method execution, and
13970 directly by VM methods.
13971 <p/>
13972 Typical examples where this event might be sent:
13973 <ul>
13974 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13975 <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13976 J2ME preloaded classes</li>
13977 </ul>
13978 Cases where this event would not be generated:
13979 <ul>
13980 <li>Allocation due to bytecodes -- for example, the <code>new</code>
13981 and <code>newarray</code> VM instructions</li>
13982 <li>Allocation due to JNI function calls -- for example,
13983 <code>AllocObject</code></li>
13984 <li>Allocations during VM initialization</li>
13985 <li>VM internal objects</li>
13986 </ul>
13987 </description>
13988 <origin>new</origin>
13989 <capabilities>
13990 <required id="can_generate_vm_object_alloc_events"></required>
13991 </capabilities>
13992 <parameters>
13993 <param id="jni_env">
13994 <outptr>
13995 <struct>JNIEnv</struct>
13996 </outptr>
13997 <description>
13998 The JNI environment of the event (current) thread
13999 </description>
14000 </param>
14001 <param id="thread">
14002 <jthread/>
14003 <description>
14004 Thread allocating the object.
14005 </description>
14006 </param>
14007 <param id="object">
14008 <jobject/>
14009 <description>
14010 JNI local reference to the object that was allocated.
14011 </description>
14012 </param>
14013 <param id="object_klass">
14014 <jclass/>
14015 <description>
14016 JNI local reference to the class of the object.
14017 </description>
14018 </param>
14019 <param id="size">
14020 <jlong/>
14021 <description>
14022 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14023 </description>
14024 </param>
14025 </parameters>
14026 </event>
14027
14028 <event label="Sampled Object Allocation"
14029 id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" filtered="thread" num="86" since="11">
14030 <description>
14031 Sent when an allocated object is sampled.
14032 By default, the sampling interval is set to 512KB. The sampling is semi-random to avoid
14033 pattern-based bias and provides an approximate overall average interval over long periods of
14034 sampling.
14035 <p/>
14036 Each thread tracks how many bytes it has allocated since it sent the last event.
14037 When the number of bytes exceeds the sampling interval, it will send another event.
14038 This implies that, on average, one object will be sampled every time a thread has
14039 allocated 512KB bytes since the last sample.
14040 <p/>
14041 Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
14042 The goal of this is to ensure high quality sampling even if allocation is
14043 happening in a fixed pattern (i.e., the same set of objects are being allocated
14044 every 512KB).
14045 <p/>
14046 If another sampling interval is required, the user can call
14047 <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
14048 representing the new sampling interval.
14049 <p/>
14050 This event is sent once the sampled allocation has been performed. It provides the object, stack trace
14051 of the allocation, the thread allocating, the size of allocation, and the object's class.
14052 <p/>
14053 A typical use case of this system is to determine where heap allocations originate.
14054 In conjunction with weak references and the function
14055 <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
14056 stack trace, and which are still live during the execution of the program.
14057 </description>
14058 <origin>new</origin>
14059 <capabilities>
14060 <required id="can_generate_sampled_object_alloc_events"></required>
14061 </capabilities>
14062 <parameters>
14063 <param id="jni_env">
14064 <outptr>
14065 <struct>JNIEnv</struct>
14066 </outptr>
14067 <description>
14068 The JNI environment of the event (current) thread.
14069 </description>
14070 </param>
14071 <param id="thread">
14072 <jthread/>
14073 <description>
14074 Thread allocating the object.
14075 </description>
14076 </param>
14077 <param id="object">
14078 <jobject/>
14079 <description>
14080 JNI local reference to the object that was allocated.
14081 </description>
14082 </param>
14083 <param id="object_klass">
14084 <jclass/>
14085 <description>
14086 JNI local reference to the class of the object
14087 </description>
14088 </param>
14089 <param id="size">
14090 <jlong/>
14091 <description>
14092 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14093 </description>
14094 </param>
14095 </parameters>
14096 </event>
14097
14098 <event label="Object Free"
14099 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
14100 <description>
14101 An Object Free event is sent when the garbage collector frees an object.
14102 Events are only sent for tagged objects--see
14103 <internallink id="Heap">heap functions</internallink>.
14104 <p/>
14105 The event handler must not use JNI functions and
14106 must not use <jvmti/> functions except those which
14107 specifically allow such use (see the raw monitor, memory management,
14108 and environment local storage functions).
14109 </description>
14110 <origin>new</origin>
14111 <capabilities>
14112 <required id="can_generate_object_free_events"></required>
14113 </capabilities>
14114 <parameters>
14115 <param id="tag">
14116 <jlong/>
14117 <description>
14118 The freed object's tag
14119 </description>
14120 </param>
14121 </parameters>
14122 </event>
14123
14124 <event label="Garbage Collection Start"
14125 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
14126 <description>
14127 A Garbage Collection Start event is sent when a
14128 garbage collection pause begins.
14129 Only stop-the-world collections are reported--that is, collections during
14130 which all threads cease to modify the state of the Java virtual machine.
14131 This means that some collectors will never generate these events.
14132 This event is sent while the VM is still stopped, thus
14133 the event handler must not use JNI functions and
14134 must not use <jvmti/> functions except those which
14135 specifically allow such use (see the raw monitor, memory management,
14136 and environment local storage functions).
14137 <p/>
14138 This event is always sent as a matched pair with
14139 <eventlink id="GarbageCollectionFinish"/>
14140 (assuming both events are enabled) and no garbage collection
14141 events will occur between them.
14142 </description>
14143 <origin>new</origin>
14144 <capabilities>
14145 <required id="can_generate_garbage_collection_events"></required>
14146 </capabilities>
14147 <parameters>
14148 </parameters>
14149 </event>
14150
14151 <event label="Garbage Collection Finish"
14152 id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
14153 <description>
14154 A Garbage Collection Finish event is sent when a
14155 garbage collection pause ends.
14156 This event is sent while the VM is still stopped, thus
14157 the event handler must not use JNI functions and
14158 must not use <jvmti/> functions except those which
14159 specifically allow such use (see the raw monitor, memory management,
14160 and environment local storage functions).
14161 <p/>
14162 Some agents may need to do post garbage collection operations that
14163 require the use of the disallowed <jvmti/> or JNI functions. For these
14164 cases an agent thread can be created which waits on a raw monitor,
14165 and the handler for the Garbage Collection Finish event simply
14166 notifies the raw monitor
14167 <p/>
14168 This event is always sent as a matched pair with
14169 <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
14170 <issue>
14171 The most important use of this event is to provide timing information,
14172 and thus additional information is not required. However,
14173 information about the collection which is "free" should be included -
14174 what that information is needs to be determined.
14175 </issue>
14176 </description>
14177 <origin>new</origin>
14178 <capabilities>
14179 <required id="can_generate_garbage_collection_events"></required>
14180 </capabilities>
14181 <parameters>
14182 </parameters>
14183 </event>
14184
14185 <elide>
14186 <event label="Verbose Output" phase="any"
14187 id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
14188 <description>
14189 Send verbose messages as strings.
14190 <issue>
14191 This format is extremely fragile, as it can change with each
14192 platform, collector and version. Alternatives include:
14193 <ul>
14194 <li>building off Java programming language M and M APIs</li>
14195 <li>XML</li>
14196 <li>key/value pairs</li>
14197 <li>removing it</li>
14198 </ul>
14199 </issue>
14200 <issue>
14201 Though this seemed trivial to implement.
14202 In the RI it appears this will be quite complex.
14203 </issue>
14204 </description>
14205 <origin>new</origin>
14206 <capabilities>
14207 </capabilities>
14208 <parameters>
14209 <param id="flag">
14210 <enum>jvmtiVerboseFlag</enum>
14211 <description>
14212 Which verbose output is being sent.
14213 </description>
14214 </param>
14215 <param id="message">
14216 <vmbuf><char/></vmbuf>
14217 <description>
14218 Message text, encoded as a
14219 <internallink id="mUTF">modified UTF-8</internallink> string.
14220 </description>
14221 </param>
14222 </parameters>
14223 </event>
14224 </elide>
14225
14226 </eventsection>
14227
14228 <datasection>
14229 <intro>
14230 <jvmti/> extends the data types defined by JNI.
14231 </intro>
14232 <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
14233 <basetype id="jboolean">
14234 <description>
14235 Holds a Java programming language <code>boolean</code>.
14236 Unsigned 8 bits.
14237 </description>
14238 </basetype>
14239 <basetype id="jchar">
14240 <description>
14241 Holds a Java programming language <code>char</code>.
14242 Unsigned 16 bits.
14243 </description>
14244 </basetype>
14245 <basetype id="jint">
14246 <description>
14247 Holds a Java programming language <code>int</code>.
14248 Signed 32 bits.
14249 </description>
14250 </basetype>
14251 <basetype id="jlong">
14252 <description>
14253 Holds a Java programming language <code>long</code>.
14254 Signed 64 bits.
14255 </description>
14256 </basetype>
14257 <basetype id="jfloat">
14258 <description>
14259 Holds a Java programming language <code>float</code>.
14260 32 bits.
14261 </description>
14262 </basetype>
14263 <basetype id="jdouble">
14264 <description>
14265 Holds a Java programming language <code>double</code>.
14266 64 bits.
14267 </description>
14268 </basetype>
14269 <basetype id="jobject">
14270 <description>
14271 Holds a Java programming language object.
14272 </description>
14273 </basetype>
14274 <basetype id="jclass">
14275 <description>
14276 Holds a Java programming language class.
14277 </description>
14278 </basetype>
14279 <basetype id="jvalue">
14280 <description>
14281 Is a union of all primitive types and <code>jobject</code>. Thus, holds any Java
14282 programming language value.
14283 </description>
14284 </basetype>
14285 <basetype id="jfieldID">
14286 <description>
14287 Identifies a Java programming language field.
14288 <code>jfieldID</code>s returned by <jvmti/> functions and events may be
14289 safely stored.
14290 </description>
14291 </basetype>
14292 <basetype id="jmethodID">
14293 <description>
14294 Identifies a Java programming language method, initializer, or constructor.
14295 <code>jmethodID</code>s returned by <jvmti/> functions and events may be
14296 safely stored. However, if the class is unloaded, they become invalid
14297 and must not be used.
14298 </description>
14299 </basetype>
14300 <basetype id="JNIEnv">
14301 <description>
14302 Pointer to the JNI function table. Pointer to this (<code>JNIEnv *</code>)
14303 is a JNI environment.
14304 </description>
14305 </basetype>
14306 </basetypes>
14307
14308 <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
14309 <basetype id="jvmtiEnv">
14310 <description>
14311 The <jvmti/> <internallink id="environments">environment</internallink> pointer.
14312 See the <internallink id="FunctionSection">Function Section</internallink>.
14313 <code>jvmtiEnv</code> points to the
14314 <internallink id="FunctionTable">function table</internallink> pointer.
14315 </description>
14316 </basetype>
14317 <basetype id="jthread">
14318 <definition>typedef jobject jthread;</definition>
14319 <description>
14320 Subtype of <datalink id="jobject"></datalink> that holds a thread.
14321 </description>
14322 </basetype>
14323 <basetype id="jthreadGroup">
14324 <definition>typedef jobject jthreadGroup;</definition>
14325 <description>
14326 Subtype of <datalink id="jobject"></datalink> that holds a thread group.
14327 </description>
14328 </basetype>
14329 <basetype id="jlocation">
14330 <definition>typedef jlong jlocation;</definition>
14331 <description>
14332 A 64 bit value, representing a monotonically increasing
14333 executable position within a method.
14334 <code>-1</code> indicates a native method.
14335 See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
14336 given VM.
14337 </description>
14338 </basetype>
14339 <basetype id="jrawMonitorID">
14340 <definition>struct _jrawMonitorID;
14341 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
14342 <description>
14343 A raw monitor.
14344 </description>
14345 </basetype>
14346 <basetype id="jvmtiError">
14347 <description>
14348 Holds an error return code.
14349 See the <internallink id="ErrorSection">Error section</internallink> for possible values.
14350 <example>
14351 typedef enum {
14352 JVMTI_ERROR_NONE = 0,
14353 JVMTI_ERROR_INVALID_THREAD = 10,
14354 ...
14355 } jvmtiError;
14356 </example>
14357 </description>
14358 </basetype>
14359 <basetype id="jvmtiEvent">
14360 <description>
14361 An identifier for an event type.
14362 See the <internallink id="EventSection">Event section</internallink> for possible values.
14363 It is guaranteed that future versions of this specification will
14364 never assign zero as an event type identifier.
14365 <example>
14366 typedef enum {
14367 JVMTI_EVENT_SINGLE_STEP = 1,
14368 JVMTI_EVENT_BREAKPOINT = 2,
14369 ...
14370 } jvmtiEvent;
14371 </example>
14372 </description>
14373 </basetype>
14374 <basetype id="jvmtiEventCallbacks" name="eventCallbacks">
14375 <description>
14376 The callbacks used for events.
14377 <example>
14378 typedef struct {
14379 jvmtiEventVMInit VMInit;
14380 jvmtiEventVMDeath VMDeath;
14381 ...
14382 } jvmtiEventCallbacks;
14383 </example>
14384 See <internallink id="jvmtiEventCallbacks">event callbacks</internallink>
14385 for the complete structure.
14386 <p/>
14387 Where, for example, the VM initialization callback is defined:
14388 <example>
14389 typedef void (JNICALL *jvmtiEventVMInit)
14390 (jvmtiEnv *jvmti_env,
14391 JNIEnv* jni_env,
14392 jthread thread);
14393 </example>
14394 See the individual events for the callback function definition.
14395 </description>
14396 </basetype>
14397 <basetype id="jniNativeInterface">
14398 <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
14399 <description>
14400 Typedef for the JNI function table <code>JNINativeInterface</code>
14401 defined in the
14402 <externallink id="jni/functions.html#interface-function-table">
14403 JNI Specification</externallink>.
14404 The JNI reference implementation defines this with an underscore.
14405 </description>
14406 </basetype>
14407 </basetypes>
14408
14409 </datasection>
14410
14411 <issuessection label="Issues">
14412 <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
14413 JVMDI requires that the agent suspend threads before calling
14414 certain sensitive functions. JVMPI requires garbage collection to be
14415 disabled before calling certain sensitive functions.
14416 It was suggested that rather than have this requirement, that
14417 VM place itself in a suitable state before performing an
14418 operation. This makes considerable sense since each VM
14419 knows its requirements and can most easily arrange a
14420 safe state.
14421 <p/>
14422 The ability to externally suspend/resume threads will, of
14423 course, remain. The ability to enable/disable garbage collection will not.
14424 <p/>
14425 This issue is resolved--suspend will not
14426 be required. The spec has been updated to reflect this.
14427 </intro>
14428
14429 <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
14430 There are a variety of approaches to sampling call stacks.
14431 The biggest bifurcation is between VM controlled and agent
14432 controlled.
14433 <p/>
14434 This issue is resolved--agent controlled
14435 sampling will be the approach.
14436 </intro>
14437
14438 <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
14439 JVMDI represents threads as jthread. JVMPI primarily
14440 uses JNIEnv* to represent threads.
14441 <p/>
14442 The Expert Group has chosen jthread as the representation
14443 for threads in <jvmti/>.
14444 JNIEnv* is sent by
14445 events since it is needed to JNI functions. JNIEnv, per the
14446 JNI spec, are not supposed to be used outside their thread.
14447 </intro>
14448
14449 <intro id="design" label="Resolved Issue: Method Representation">
14450 The JNI spec allows an implementation to depend on jclass/jmethodID
14451 pairs, rather than simply a jmethodID, to reference a method.
14452 JVMDI, for consistency, choose the same representation.
14453 JVMPI, however, specifies that a jmethodID alone maps to a
14454 method. Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
14455 pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
14456 In fact, any JVM implementation that supports JVMPI must have
14457 such a representation.
14458 <jvmti/> will use jmethodID as a unique representation of a method
14459 (no jclass is used).
14460 There should be efficiency gains, particularly in
14461 functionality like stack dumping, to this representation.
14462 <p/>
14463 Note that fields were not used in JVMPI and that the access profile
14464 of fields differs from methods--for implementation efficiency
14465 reasons, a jclass/jfieldID pair will still be needed for field
14466 reference.
14467 </intro>
14468
14469 <intro id="localReferenceIssue" label="Resolved Issue: Local References">
14470 Functions return local references.
14471 </intro>
14472
14473 <intro id="frameRep" label="Resolved Issue: Representation of frames">
14474 In JVMDI, a frame ID is used to represent a frame. Problem with this
14475 is that a VM must track when a frame becomes invalid, a far better
14476 approach, and the one used in <jvmti/>, is to reference frames by depth.
14477 </intro>
14478
14479 <intro id="requiredCapabilities" label="Issue: Required Capabilities">
14480 Currently, having a required capabilities means that the functionality
14481 is optional. Capabilities are useful even for required functionality
14482 since they can inform the VM is needed set-up. Thus, there should be
14483 a set of capabilities that a conformant implementation must provide
14484 (if requested during Agent_OnLoad).
14485 </intro>
14486
14487 <intro id="taghint" label="Proposal: add tag hint function">
14488 A hint of the percentage of objects that will be tagged would
14489 help the VM pick a good implementation.
14490 </intro>
14491
14492 <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
14493 How difficult or easy would be to extend the monitor_info category to include
14494 <pre>
14495 - current number of monitors
14496 - enumeration of monitors
14497 - enumeration of threads waiting on a given monitor
14498 </pre>
14499 The reason for my question is the fact that current get_monitor_info support
14500 requires the agent to specify a given thread to get the info which is probably
14501 OK in the profiling/debugging space, while in the monitoring space the agent
14502 could be watching the monitor list and then decide which thread to ask for
14503 the info. You might ask why is this important for monitoring .... I think it
14504 can aid in the detection/prediction of application contention caused by hot-locks.
14505 </intro>
14506 </issuessection>
14507
14508 <changehistory id="ChangeHistory" update="09/05/07">
14509 <intro>
14510 The <jvmti/> specification is an evolving document with major, minor,
14511 and micro version numbers.
14512 A released version of the specification is uniquely identified
14513 by its major and minor version.
14514 The functions, events, and capabilities in this specification
14515 indicate a "Since" value which is the major and minor version in
14516 which it was introduced.
14517 The version of the specification implemented by the VM can
14518 be retrieved at runtime with the <functionlink id="GetVersionNumber"/>
14519 function.
14520 </intro>
14521 <change date="14 Nov 2002">
14522 Converted to XML document.
14523 </change>
14524 <change date="14 Nov 2002">
14525 Elided heap dump functions (for now) since what was there
14526 was wrong.
14527 </change>
14528 <change date="18 Nov 2002">
14529 Added detail throughout.
14530 </change>
14531 <change date="18 Nov 2002">
14532 Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
14533 </change>
14534 <change date="19 Nov 2002">
14535 Added AsyncGetStackTrace.
14536 </change>
14537 <change date="19 Nov 2002">
14538 Added jframeID return to GetStackTrace.
14539 </change>
14540 <change date="19 Nov 2002">
14541 Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
14542 since they are redundant with GetStackTrace.
14543 </change>
14544 <change date="19 Nov 2002">
14545 Elided ClearAllBreakpoints since it has always been redundant.
14546 </change>
14547 <change date="19 Nov 2002">
14548 Added GetSystemProperties.
14549 </change>
14550 <change date="19 Nov 2002">
14551 Changed the thread local storage functions to use jthread.
14552 </change>
14553 <change date="20 Nov 2002">
14554 Added GetJLocationFormat.
14555 </change>
14556 <change date="22 Nov 2002">
14557 Added events and introductory text.
14558 </change>
14559 <change date="22 Nov 2002">
14560 Cross reference type and constant definitions.
14561 </change>
14562 <change date="24 Nov 2002">
14563 Added DTD.
14564 </change>
14565 <change date="24 Nov 2002">
14566 Added capabilities function section.
14567 </change>
14568 <change date="29 Nov 2002">
14569 Assign capabilities to each function and event.
14570 </change>
14571 <change date="29 Nov 2002">
14572 Add <internallink id="jniIntercept">JNI interception functions</internallink>.
14573 </change>
14574 <change date="30 Nov 2002">
14575 Auto generate SetEventNotificationMode capabilities.
14576 </change>
14577 <change date="30 Nov 2002">
14578 Add <eventlink id="VMObjectAlloc"></eventlink> event.
14579 </change>
14580 <change date="30 Nov 2002">
14581 Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
14582 </change>
14583 <change date="30 Nov 2002">
14584 Add const to declarations.
14585 </change>
14586 <change date="30 Nov 2002">
14587 Change method exit and frame pop to send on exception.
14588 </change>
14589 <change date="1 Dec 2002">
14590 Add ForceGarbageCollection.
14591 </change>
14592 <change date="2 Dec 2002">
14593 Redo Xrun section; clarify GetStackTrace and add example;
14594 Fix width problems; use "agent" consistently.
14595 </change>
14596 <change date="8 Dec 2002">
14597 Remove previous start-up intro.
14598 Add <internallink id="environments"><jvmti/> Environments</internallink>
14599 section.
14600 </change>
14601 <change date="8 Dec 2002">
14602 Add <functionlink id="DisposeEnvironment"></functionlink>.
14603 </change>
14604 <change date="9 Dec 2002">
14605 Numerous minor updates.
14606 </change>
14607 <change date="15 Dec 2002">
14608 Add heap profiling functions added:
14609 get/set annotation, iterate live objects/heap.
14610 Add heap profiling functions place holder added:
14611 heap roots.
14612 Heap profiling event added: object free.
14613 Heap profiling event redesigned: vm object allocation.
14614 Heap profiling event placeholders added: garbage collection start/finish.
14615 Native method bind event added.
14616 </change>
14617 <change date="19 Dec 2002">
14618 Revamp suspend/resume functions.
14619 Add origin information with jvmdi tag.
14620 Misc fixes.
14621 </change>
14622 <change date="24 Dec 2002">
14623 Add semantics to types.
14624 </change>
14625 <change date="27 Dec 2002">
14626 Add local reference section.
14627 Autogenerate parameter descriptions from types.
14628 </change>
14629 <change date="28 Dec 2002">
14630 Document that RunAgentThread sends threadStart.
14631 </change>
14632 <change date="29 Dec 2002">
14633 Remove redundant local ref and dealloc warning.
14634 Convert GetRawMonitorName to allocated buffer.
14635 Add GenerateEvents.
14636 </change>
14637 <change date="30 Dec 2002">
14638 Make raw monitors a type and rename to "jrawMonitorID".
14639 </change>
14640 <change date="1 Jan 2003">
14641 Include origin information.
14642 Clean-up JVMDI issue references.
14643 Remove Deallocate warnings which are now automatically generated.
14644 </change>
14645 <change date="2 Jan 2003">
14646 Fix representation issues for jthread.
14647 </change>
14648 <change date="3 Jan 2003">
14649 Make capabilities buffered out to 64 bits - and do it automatically.
14650 </change>
14651 <change date="4 Jan 2003">
14652 Make constants which are enumeration into enum types.
14653 Parameters now of enum type.
14654 Clean-up and index type section.
14655 Replace remaining datadef entities with callback.
14656 </change>
14657 <change date="7 Jan 2003">
14658 Correct GenerateEvents description.
14659 More internal semantics work.
14660 </change>
14661 <change date="9 Jan 2003">
14662 Replace previous GetSystemProperties with two functions
14663 which use allocated information instead fixed.
14664 Add SetSystemProperty.
14665 More internal semantics work.
14666 </change>
14667 <change date="12 Jan 2003">
14668 Add varargs to end of SetEventNotificationMode.
14669 </change>
14670 <change date="20 Jan 2003">
14671 Finish fixing spec to reflect that alloc sizes are jlong.
14672 </change>
14673 <change date="22 Jan 2003">
14674 Allow NULL as RunAgentThread arg.
14675 </change>
14676 <change date="22 Jan 2003">
14677 Fixed names to standardized naming convention
14678 Removed AsyncGetStackTrace.
14679 </change>
14680 <change date="29 Jan 2003">
14681 Since we are using jthread, removed GetThread.
14682 </change>
14683 <change date="31 Jan 2003">
14684 Change GetFieldName to allow NULLs like GetMethodName.
14685 </change>
14686 <change date="29 Feb 2003" version="v40">
14687 Rewrite the introductory text, adding sections on
14688 start-up, environments and bytecode instrumentation.
14689 Change the command line arguments per EG discussions.
14690 Add an introduction to the capabilities section.
14691 Add the extension mechanism category and functions.
14692 Mark for deletion, but clarified anyhow, SuspendAllThreads.
14693 Rename IterateOverLiveObjects to IterateOverReachableObjects and
14694 change the text accordingly.
14695 Clarify IterateOverHeap.
14696 Clarify CompiledMethodLoad.
14697 Discuss prerequisite state for Calling Functions.
14698 Clarify SetAllocationHooks.
14699 Added issues ("To be resolved:") through-out.
14700 And so on...
14701 </change>
14702 <change date="6 Mar 2003" version="v41">
14703 Remove struct from the call to GetOwnedMonitorInfo.
14704 Automatically generate most error documentation, remove
14705 (rather broken) hand written error doc.
14706 Better describe capability use (empty initial set).
14707 Add min value to jint params.
14708 Remove the capability can_access_thread_local_storage.
14709 Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
14710 same for *NOT_IMPLEMENTED.
14711 Description fixes.
14712 </change>
14713 <change date="8 Mar 2003" version="v42">
14714 Rename GetClassSignature to GetClassName.
14715 Rename IterateOverClassObjects to IterateOverInstancesOfClass.
14716 Remove GetMaxStack (operand stack isn't used in <jvmti/>).
14717 Description fixes: define launch-time, remove native frame pop
14718 from PopFrame, and assorted clarifications.
14719 </change>
14720 <change date="8 Mar 2003" version="v43">
14721 Fix minor editing problem.
14722 </change>
14723 <change date="10 Mar 2003" version="v44">
14724 Add phase information.
14725 Remap (compact) event numbers.
14726 </change>
14727 <change date="11 Mar 2003" version="v45">
14728 More phase information - allow "any".
14729 Elide raw monitor queries and events.
14730 Minor description fixes.
14731 </change>
14732 <change date="12 Mar 2003" version="v46">
14733 Add GetPhase.
14734 Use "phase" through document.
14735 Elide GetRawMonitorName.
14736 Elide GetObjectMonitors.
14737 </change>
14738 <change date="12 Mar 2003" version="v47">
14739 Fixes from link, XML, and spell checking.
14740 Auto-generate the callback structure.
14741 </change>
14742 <change date="13 Mar 2003" version="v48">
14743 One character XML fix.
14744 </change>
14745 <change date="13 Mar 2003" version="v49">
14746 Change function parameter names to be consistent with
14747 event parameters (fooBarBaz becomes foo_bar_baz).
14748 </change>
14749 <change date="14 Mar 2003" version="v50">
14750 Fix broken link. Fix thread markers.
14751 </change>
14752 <change date="14 Mar 2003" version="v51">
14753 Change constants so they are under 128 to workaround
14754 compiler problems.
14755 </change>
14756 <change date="23 Mar 2003" version="v52">
14757 Overhaul capabilities. Separate GetStackTrace into
14758 GetStackTrace and GetStackFrames.
14759 </change>
14760 <change date="8 Apr 2003" version="v54">
14761 Use depth instead of jframeID to reference frames.
14762 Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
14763 Remove frame arg from events.
14764 </change>
14765 <change date="9 Apr 2003" version="v55">
14766 Remove GetObjectWithAnnotation since tests show buffered approach more efficient.
14767 Add missing annotation_count to GetObjectsWithAnnotations
14768 </change>
14769 <change date="10 Apr 2003" version="v56">
14770 Remove confusing parenthetical statement in GetObjectsWithAnnotations
14771 </change>
14772 <change date="13 Apr 2003" version="v58">
14773 Replace jclass/jmethodID representation of method with simply jmethodID;
14774 Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
14775 Replace can_access_frames with can_access_local_variables; remove from purely stack access.
14776 Use can_get_synthetic_attribute; fix description.
14777 Clarify that zero length arrays must be deallocated.
14778 Clarify RelinquishCapabilities.
14779 Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
14780 </change>
14781 <change date="27 Apr 2003" version="v59">
14782 Remove lingering indirect references to OBSOLETE_METHOD_ID.
14783 </change>
14784 <change date="4 May 2003" version="v60">
14785 Allow DestroyRawMonitor during OnLoad.
14786 </change>
14787 <change date="7 May 2003" version="v61">
14788 Added not monitor owner error return to DestroyRawMonitor.
14789 </change>
14790 <change date="13 May 2003" version="v62">
14791 Clarify semantics of raw monitors.
14792 Change flags on <code>GetThreadStatus</code>.
14793 <code>GetClassLoader</code> return NULL for the bootstrap class loader.
14794 Add <code>GetClassName</code> issue.
14795 Define local variable signature.
14796 Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
14797 Remove over specification in <code>GetObjectsWithAnnotations</code>.
14798 Elide <code>SetAllocationHooks</code>.
14799 Elide <code>SuspendAllThreads</code>.
14800 </change>
14801 <change date="14 May 2003" version="v63">
14802 Define the data type <code>jvmtiEventCallbacks</code>.
14803 Zero length allocations return NULL.
14804 Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.
14805 Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
14806 </change>
14807 <change date="15 May 2003" version="v64">
14808 Better wording, per review.
14809 </change>
14810 <change date="15 May 2003" version="v65">
14811 First Alpha.
14812 Make jmethodID and jfieldID unique, jclass not used.
14813 </change>
14814 <change date="27 May 2003" version="v66">
14815 Fix minor XSLT errors.
14816 </change>
14817 <change date="13 June 2003" version="v67">
14818 Undo making jfieldID unique (jmethodID still is).
14819 </change>
14820 <change date="17 June 2003" version="v68">
14821 Changes per June 11th Expert Group meeting --
14822 Overhaul Heap functionality: single callback,
14823 remove GetHeapRoots, add reachable iterators,
14824 and rename "annotation" to "tag".
14825 NULL thread parameter on most functions is current
14826 thread.
14827 Add timers.
14828 Remove ForceExit.
14829 Add GetEnvironmentLocalStorage.
14830 Add verbose flag and event.
14831 Add AddToBootstrapClassLoaderSearch.
14832 Update ClassFileLoadHook.
14833 </change>
14834 <change date="18 June 2003" version="v69">
14835 Clean up issues sections.
14836 Rename GetClassName back to GetClassSignature and
14837 fix description.
14838 Add generic signature to GetClassSignature,
14839 GetFieldSignature, GetMethodSignature, and
14840 GetLocalVariableTable.
14841 Elide EstimateCostOfCapabilities.
14842 Clarify that the system property functions operate
14843 on the VM view of system properties.
14844 Clarify Agent_OnLoad.
14845 Remove "const" from JNIEnv* in events.
14846 Add metadata accessors.
14847 </change>
14848 <change date="18 June 2003" version="v70">
14849 Add start_depth to GetStackTrace.
14850 Move system properties to a new category.
14851 Add GetObjectSize.
14852 Remove "X" from command line flags.
14853 XML, HTML, and spell check corrections.
14854 </change>
14855 <change date="19 June 2003" version="v71">
14856 Fix JVMTI_HEAP_ROOT_THREAD to be 6.
14857 Make each synopsis match the function name.
14858 Fix unclear wording.
14859 </change>
14860 <change date="26 June 2003" version="v72">
14861 SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
14862 to be set to NULL.
14863 NotifyFramePop, GetFrameLocationm and all the local variable operations
14864 needed to have their wording about frames fixed.
14865 Grammar and clarity need to be fixed throughout.
14866 Capitalization and puntuation need to be consistent.
14867 Need micro version number and masks for accessing major, minor, and micro.
14868 The error code lists should indicate which must be returned by
14869 an implementation.
14870 The command line properties should be visible in the properties functions.
14871 Disallow popping from the current thread.
14872 Allow implementations to return opaque frame error when they cannot pop.
14873 The NativeMethodBind event should be sent during any phase.
14874 The DynamicCodeGenerated event should be sent during any phase.
14875 The following functions should be allowed to operate before VMInit:
14876 Set/GetEnvironmentLocalStorage
14877 GetMethodDeclaringClass
14878 GetClassSignature
14879 GetClassModifiers
14880 IsInterface
14881 IsArrayClass
14882 GetMethodName
14883 GetMethodModifiers
14884 GetMaxLocals
14885 GetArgumentsSize
14886 GetLineNumberTable
14887 GetMethodLocation
14888 IsMethodNative
14889 IsMethodSynthetic.
14890 Other changes (to XSL):
14891 Argument description should show asterisk after not before pointers.
14892 NotifyFramePop, GetFrameLocationm and all the local variable operations
14893 should hsve the NO_MORE_FRAMES error added.
14894 Not alive threads should have a different error return than invalid thread.
14895 </change>
14896 <change date="7 July 2003" version="v73">
14897 VerboseOutput event was missing message parameter.
14898 Minor fix-ups.
14899 </change>
14900 <change date="14 July 2003" version="v74">
14901 Technical Publications Department corrections.
14902 Allow thread and environment local storage to be set to NULL.
14903 </change>
14904 <change date="23 July 2003" version="v75">
14905 Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
14906 Add JNICALL to callbacks (XSL).
14907 Document JNICALL requirement for both events and callbacks (XSL).
14908 Restrict RedefineClasses to methods and attributes.
14909 Elide the VerboseOutput event.
14910 VMObjectAlloc: restrict when event is sent and remove method parameter.
14911 Finish loose ends from Tech Pubs edit.
14912 </change>
14913 <change date="24 July 2003" version="v76">
14914 Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
14915 </change>
14916 <change date="24 July 2003" version="v77">
14917 XML fixes.
14918 Minor text clarifications and corrections.
14919 </change>
14920 <change date="24 July 2003" version="v78">
14921 Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
14922 Clarify that stack frames are JVM Spec frames.
14923 Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
14924 and can_get_source_debug_extension.
14925 PopFrame cannot have a native calling method.
14926 Removed incorrect statement in GetClassloaderClasses
14927 (see <vmspec chapter="4.4"/>).
14928 </change>
14929 <change date="24 July 2003" version="v79">
14930 XML and text fixes.
14931 Move stack frame description into Stack Frame category.
14932 </change>
14933 <change date="26 July 2003" version="v80">
14934 Allow NULL (means bootstrap loader) for GetClassloaderClasses.
14935 Add new heap reference kinds for references from classes.
14936 Add timer information struct and query functions.
14937 Add AvailableProcessors.
14938 Rename GetOtherThreadCpuTime to GetThreadCpuTime.
14939 Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
14940 to SetEventNotification mode.
14941 Add initial thread to the VM_INIT event.
14942 Remove platform assumptions from AddToBootstrapClassLoaderSearch.
14943 </change>
14944 <change date="26 July 2003" version="v81">
14945 Grammar and clarity changes per review.
14946 </change>
14947 <change date="27 July 2003" version="v82">
14948 More grammar and clarity changes per review.
14949 Add Agent_OnUnload.
14950 </change>
14951 <change date="28 July 2003" version="v83">
14952 Change return type of Agent_OnUnload to void.
14953 </change>
14954 <change date="28 July 2003" version="v84">
14955 Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
14956 </change>
14957 <change date="28 July 2003" version="v85">
14958 Steal java.lang.Runtime.availableProcessors() wording for
14959 AvailableProcessors().
14960 Guarantee that zero will never be an event ID.
14961 Remove some issues which are no longer issues.
14962 Per review, rename and more completely document the timer
14963 information functions.
14964 </change>
14965 <change date="29 July 2003" version="v86">
14966 Non-spec visible change to XML controlled implementation:
14967 SetThreadLocalStorage must run in VM mode.
14968 </change>
14969 <change date="5 August 2003" version="0.1.87">
14970 Add GetErrorName.
14971 Add varargs warning to jvmtiExtensionEvent.
14972 Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
14973 Remove unused can_get_exception_info capability.
14974 Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
14975 Fix jvmtiExtensionFunctionInfo.func declared type.
14976 Extension function returns error code.
14977 Use new version numbering.
14978 </change>
14979 <change date="5 August 2003" version="0.2.88">
14980 Remove the ClassUnload event.
14981 </change>
14982 <change date="8 August 2003" version="0.2.89">
14983 Heap reference iterator callbacks return an enum that
14984 allows outgoing object references to be ignored.
14985 Allow JNIEnv as a param type to extension events/functions.
14986 </change>
14987 <change date="15 August 2003" version="0.2.90">
14988 Fix a typo.
14989 </change>
14990 <change date="2 September 2003" version="0.2.91">
14991 Remove all metadata functions: GetClassMetadata,
14992 GetFieldMetadata, and GetMethodMetadata.
14993 </change>
14994 <change date="1 October 2003" version="0.2.92">
14995 Mark the functions Allocate. Deallocate, RawMonitor*,
14996 SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage
14997 as safe for use in heap callbacks and GC events.
14998 </change>
14999 <change date="24 November 2003" version="0.2.93">
15000 Add pass through opaque user data pointer to heap iterate
15001 functions and callbacks.
15002 In the CompiledMethodUnload event, send the code address.
15003 Add GarbageCollectionOccurred event.
15004 Add constant pool reference kind.
15005 Mark the functions CreateRawMonitor and DestroyRawMonitor
15006 as safe for use in heap callbacks and GC events.
15007 Clarify: VMDeath, GetCurrentThreadCpuTimerInfo,
15008 GetThreadCpuTimerInfo, IterateOverReachableObjects,
15009 IterateOverObjectsReachableFromObject, GetTime and
15010 JVMTI_ERROR_NULL_POINTER.
15011 Add missing errors to: GenerateEvents and
15012 AddToBootstrapClassLoaderSearch.
15013 Fix description of ClassFileLoadHook name parameter.
15014 In heap callbacks and GC/ObjectFree events, specify
15015 that only explicitly allowed functions can be called.
15016 Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
15017 GetTimerInfo, and GetTime during callback.
15018 Allow calling SetTag/GetTag during the onload phase.
15019 SetEventNotificationMode, add: error attempted inappropriate
15020 thread level control.
15021 Remove jvmtiExceptionHandlerEntry.
15022 Fix handling of native methods on the stack --
15023 location_ptr param of GetFrameLocation, remove
15024 JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
15025 jvmtiFrameInfo.location, and jlocation.
15026 Remove typo (from JVMPI) implying that the MonitorWaited
15027 event is sent on sleep.
15028 </change>
15029 <change date="25 November 2003" version="0.2.94">
15030 Clarifications and typos.
15031 </change>
15032 <change date="3 December 2003" version="0.2.95">
15033 Allow NULL user_data in heap iterators.
15034 </change>
15035 <change date="28 January 2004" version="0.2.97">
15036 Add GetThreadState, deprecate GetThreadStatus.
15037 </change>
15038 <change date="29 January 2004" version="0.2.98">
15039 INVALID_SLOT and TYPE_MISMATCH errors should be optional.
15040 </change>
15041 <change date="12 February 2004" version="0.2.102">
15042 Remove MonitorContendedExit.
15043 Added JNIEnv parameter to VMObjectAlloc.
15044 Clarified definition of class_tag and referrer_index
15045 parameters to heap callbacks.
15046 </change>
15047 <change date="16 February 2004" version="0.2.103">
15048 Document JAVA_TOOL_OPTIONS.
15049 </change>
15050 <change date="17 February 2004" version="0.2.105">
15051 Divide start phase into primordial and start.
15052 Add VMStart event
15053 Change phase associations of functions and events.
15054 </change>
15055 <change date="18 February 2004" version="0.3.6">
15056 Elide deprecated GetThreadStatus.
15057 Bump minor version, subtract 100 from micro version
15058 </change>
15059 <change date="18 February 2004" version="0.3.7">
15060 Document that timer nanosecond values are unsigned.
15061 Clarify text having to do with native methods.
15062 </change>
15063 <change date="19 February 2004" version="0.3.8">
15064 Fix typos.
15065 Remove elided deprecated GetThreadStatus.
15066 </change>
15067 <change date="23 February 2004" version="0.3.9">
15068 Require NotifyFramePop to act on suspended threads.
15069 </change>
15070 <change date="24 February 2004" version="0.3.10">
15071 Add capabilities
15072 (<internallink id="jvmtiCapabilities.can_redefine_any_class"
15073 ><code>can_redefine_any_class</code></internallink>
15074 and
15075 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
15076 ><code>can_generate_all_class_hook_events</code></internallink>)
15077 and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>)
15078 which allow some classes to be unmodifiable.
15079 </change>
15080 <change date="28 February 2004" version="0.3.11">
15081 Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
15082 </change>
15083 <change date="8 March 2004" version="0.3.12">
15084 Clarified CompiledMethodUnload so that it is clear the event
15085 may be posted after the class has been unloaded.
15086 </change>
15087 <change date="5 March 2004" version="0.3.13">
15088 Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
15089 </change>
15090 <change date="13 March 2004" version="0.3.14">
15091 Added guideline for the use of the JNI FindClass function in event
15092 callback functions.
15093 </change>
15094 <change date="15 March 2004" version="0.3.15">
15095 Add GetAllStackTraces and GetThreadListStackTraces.
15096 </change>
15097 <change date="19 March 2004" version="0.3.16">
15098 ClassLoad and ClassPrepare events can be posted during start phase.
15099 </change>
15100 <change date="25 March 2004" version="0.3.17">
15101 Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
15102 GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
15103 </change>
15104 <change date="29 March 2004" version="0.3.18">
15105 Return the timer kind in the timer information structure.
15106 </change>
15107 <change date="31 March 2004" version="0.3.19">
15108 Spec clarifications:
15109 JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
15110 ForceGarbageCollection does not run finalizers.
15111 The context of the specification is the Java platform.
15112 Warn about early instrumentation.
15113 </change>
15114 <change date="1 April 2004" version="0.3.20">
15115 Refinements to the above clarifications and
15116 Clarify that an error returned by Agent_OnLoad terminates the VM.
15117 </change>
15118 <change date="1 April 2004" version="0.3.21">
15119 Array class creation does not generate a class load event.
15120 </change>
15121 <change date="7 April 2004" version="0.3.22">
15122 Align thread state hierarchy more closely with java.lang.Thread.State.
15123 </change>
15124 <change date="12 April 2004" version="0.3.23">
15125 Clarify the documentation of thread state.
15126 </change>
15127 <change date="19 April 2004" version="0.3.24">
15128 Remove GarbageCollectionOccurred event -- can be done by agent.
15129 </change>
15130 <change date="22 April 2004" version="0.3.25">
15131 Define "command-line option".
15132 </change>
15133 <change date="29 April 2004" version="0.3.26">
15134 Describe the intended use of bytecode instrumentation.
15135 Fix description of extension event first parameter.
15136 </change>
15137 <change date="30 April 2004" version="0.3.27">
15138 Clarification and typos.
15139 </change>
15140 <change date="18 May 2004" version="0.3.28">
15141 Remove DataDumpRequest event.
15142 </change>
15143 <change date="18 May 2004" version="0.3.29">
15144 Clarify RawMonitorWait with zero timeout.
15145 Clarify thread state after RunAgentThread.
15146 </change>
15147 <change date="24 May 2004" version="0.3.30">
15148 Clean-up: fix bad/old links, etc.
15149 </change>
15150 <change date="30 May 2004" version="0.3.31">
15151 Clarifications including:
15152 All character strings are modified UTF-8.
15153 Agent thread visibiity.
15154 Meaning of obsolete method version.
15155 Thread invoking heap callbacks,
15156 </change>
15157 <change date="1 June 2004" version="1.0.32">
15158 Bump major.minor version numbers to "1.0".
15159 </change>
15160 <change date="2 June 2004" version="1.0.33">
15161 Clarify interaction between ForceGarbageCollection
15162 and ObjectFree.
15163 </change>
15164 <change date="6 June 2004" version="1.0.34">
15165 Restrict AddToBootstrapClassLoaderSearch and
15166 SetSystemProperty to the OnLoad phase only.
15167 </change>
15168 <change date="11 June 2004" version="1.0.35">
15169 Fix typo in SetTag.
15170 </change>
15171 <change date="18 June 2004" version="1.0.36">
15172 Fix trademarks.
15173 Add missing parameter in example GetThreadState usage.
15174 </change>
15175 <change date="4 August 2004" version="1.0.37">
15176 Copyright updates.
15177 </change>
15178 <change date="5 November 2004" version="1.0.38">
15179 Add missing function table layout.
15180 Add missing description of C++ member function format of functions.
15181 Clarify that name in CFLH can be NULL.
15182 Released as part of <tm>J2SE</tm> 5.0.
15183 </change>
15184 <change date="24 April 2005" version="1.1.47">
15185 Bump major.minor version numbers to "1.1".
15186 Add ForceEarlyReturn* functions.
15187 Add GetOwnedMonitorStackDepthInfo function.
15188 Add GetCurrentThread function.
15189 Add "since" version marker.
15190 Add AddToSystemClassLoaderSearch.
15191 Allow AddToBootstrapClassLoaderSearch be used in live phase.
15192 Fix historic rubbish in the descriptions of the heap_object_callback
15193 parameter of IterateOverHeap and IterateOverInstancesOfClass functions;
15194 disallow NULL for this parameter.
15195 Clarify, correct and make consistent: wording about current thread,
15196 opaque frames and insufficient number of frames in PopFrame.
15197 Consistently use "current frame" rather than "topmost".
15198 Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
15199 by making them compatible with those in ForceEarlyReturn*.
15200 Many other clarifications and wording clean ups.
15201 </change>
15202 <change date="25 April 2005" version="1.1.48">
15203 Add GetConstantPool.
15204 Switch references to the first edition of the VM Spec, to the seconds edition.
15205 </change>
15206 <change date="26 April 2005" version="1.1.49">
15207 Clarify minor/major version order in GetConstantPool.
15208 </change>
15209 <change date="26 April 2005" version="1.1.50">
15210 Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
15211 Reassign GetOwnedMonitorStackDepthInfo to position 153.
15212 Break out Class Loader Search in its own documentation category.
15213 Deal with overly long lines in XML source.
15214 </change>
15215 <change date="29 April 2005" version="1.1.51">
15216 Allow agents be started in the live phase.
15217 Added paragraph about deploying agents.
15218 </change>
15219 <change date="30 April 2005" version="1.1.52">
15220 Add specification description to SetNativeMethodPrefix(es).
15221 Better define the conditions on GetConstantPool.
15222 </change>
15223 <change date="30 April 2005" version="1.1.53">
15224 Break out the GetClassVersionNumber function from GetConstantPool.
15225 Clean-up the references to the VM Spec.
15226 </change>
15227 <change date="1 May 2005" version="1.1.54">
15228 Allow SetNativeMethodPrefix(es) in any phase.
15229 Add clarifications about the impact of redefinition on GetConstantPool.
15230 </change>
15231 <change date="2 May 2005" version="1.1.56">
15232 Various clarifications to SetNativeMethodPrefix(es).
15233 </change>
15234 <change date="2 May 2005" version="1.1.57">
15235 Add missing performance warning to the method entry event.
15236 </change>
15237 <change date="5 May 2005" version="1.1.58">
15238 Remove internal JVMDI support.
15239 </change>
15240 <change date="8 May 2005" version="1.1.59">
15241 Add <functionlink id="RetransformClasses"/>.
15242 Revamp the bytecode instrumentation documentation.
15243 Change <functionlink id="IsMethodObsolete"/> to no longer
15244 require the can_redefine_classes capability.
15245 </change>
15246 <change date="11 May 2005" version="1.1.63">
15247 Clarifications for retransformation.
15248 </change>
15249 <change date="11 May 2005" version="1.1.64">
15250 Clarifications for retransformation, per review.
15251 Lock "retransformation (in)capable" at class load enable time.
15252 </change>
15253 <change date="4 June 2005" version="1.1.67">
15254 Add new heap functionity which supports reporting primitive values,
15255 allows setting the referrer tag, and has more powerful filtering:
15256 FollowReferences, IterateThroughHeap, and their associated
15257 callbacks, structs, enums, and constants.
15258 </change>
15259 <change date="4 June 2005" version="1.1.68">
15260 Clarification.
15261 </change>
15262 <change date="6 June 2005" version="1.1.69">
15263 FollowReferences, IterateThroughHeap: Put callbacks in a struct;
15264 Add missing error codes; reduce bits in the visit control flags.
15265 </change>
15266 <change date="14 June 2005" version="1.1.70">
15267 More on new heap functionity: spec clean-up per review.
15268 </change>
15269 <change date="15 June 2005" version="1.1.71">
15270 More on new heap functionity: Rename old heap section to Heap (1.0).
15271 </change>
15272 <change date="21 June 2005" version="1.1.72">
15273 Fix typos.
15274 </change>
15275 <change date="27 June 2005" version="1.1.73">
15276 Make referrer info structure a union.
15277 </change>
15278 <change date="9 September 2005" version="1.1.74">
15279 In new heap functions:
15280 Add missing superclass reference kind.
15281 Use a single scheme for computing field indexes.
15282 Remove outdated references to struct based referrer info.
15283 </change>
15284 <change date="12 September 2005" version="1.1.75">
15285 Don't callback during FollowReferences on frivolous java.lang.Object superclass.
15286 </change>
15287 <change date="13 September 2005" version="1.1.76">
15288 In string primitive callback, length now Unicode length.
15289 In array and string primitive callbacks, value now "const".
15290 Note possible compiler impacts on setting JNI function table.
15291 </change>
15292 <change date="13 September 2005" version="1.1.77">
15293 GetClassVersionNumbers() and GetConstantPool() should return
15294 error on array or primitive class.
15295 </change>
15296 <change date="14 September 2005" version="1.1.78">
15297 Grammar fixes.
15298 </change>
15299 <change date="26 September 2005" version="1.1.79">
15300 Add IsModifiableClass query.
15301 </change>
15302 <change date="9 February 2006" version="1.1.81">
15303 Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
15304 </change>
15305 <change date="13 February 2006" version="1.1.82">
15306 Doc fixes: update can_redefine_any_class to include retransform.
15307 Clarify that exception events cover all Throwables.
15308 In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
15309 Clarify fields reported in Primitive Field Callback -- static vs instance.
15310 Repair confusing names of heap types, including callback names.
15311 Require consistent usage of stack depth in the face of thread launch methods.
15312 Note incompatibility of <jvmti/> memory management with other systems.
15313 </change>
15314 <change date="14 February 2006" version="1.1.85">
15315 Fix typos and missing renames.
15316 </change>
15317 <change date="13 March 2006" version="1.1.86">
15318 Clarify that jmethodIDs and jfieldIDs can be saved.
15319 Clarify that Iterate Over Instances Of Class includes subclasses.
15320 </change>
15321 <change date="14 March 2006" version="1.1.87">
15322 Better phrasing.
15323 </change>
15324 <change date="16 March 2006" version="1.1.88">
15325 Match the referrer_index for static fields in Object Reference Callback
15326 with the Reference Implementation (and all other known implementations);
15327 that is, make it match the definition for instance fields.
15328 In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover
15329 an invalid thread in the list; and specify that not started threads
15330 return empty stacks.
15331 </change>
15332 <change date="17 March 2006" version="1.1.89">
15333 Typo.
15334 </change>
15335 <change date="25 March 2006" version="1.1.90">
15336 Typo.
15337 </change>
15338 <change date="6 April 2006" version="1.1.91">
15339 Remove restrictions on AddToBootstrapClassLoaderSearch and
15340 AddToSystemClassLoaderSearch.
15341 </change>
15342 <change date="1 May 2006" version="1.1.93">
15343 Changed spec to return -1 for monitor stack depth for the
15344 implementation which can not determine stack depth.
15345 </change>
15346 <change date="3 May 2006" version="1.1.94">
15347 Corrections for readability and accuracy courtesy of Alan Pratt of IBM.
15348 List the object relationships reported in FollowReferences.
15349 </change>
15350 <change date="5 May 2006" version="1.1.95">
15351 Clarify the object relationships reported in FollowReferences.
15352 </change>
15353 <change date="28 June 2006" version="1.1.98">
15354 Clarify DisposeEnvironment; add warning.
15355 Fix typos in SetLocalXXX "retrieve" => "set".
15356 Clarify that native method prefixes must remain set while used.
15357 Clarify that exactly one Agent_OnXXX is called per agent.
15358 Clarify that library loading is independent from start-up.
15359 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
15360 </change>
15361 <change date="31 July 2006" version="1.1.99">
15362 Clarify the interaction between functions and exceptions.
15363 Clarify and give examples of field indices.
15364 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
15365 Update links to point to Java 6.
15366 </change>
15367 <change date="6 August 2006" version="1.1.102">
15368 Add ResourceExhaustedEvent.
15369 </change>
15370 <change date="11 October 2012" version="1.2.2">
15371 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
15372 </change>
15373 <change date="19 June 2013" version="1.2.3">
15374 Added support for statically linked agents.
15375 </change>
15376 <change date="13 October 2016" version="9.0.0">
15377 Support for modules:
15378 - The majorversion is 9 now
15379 - The ClassFileLoadHook events are not sent during the primordial phase anymore.
15380 - Allow CompiledMethodLoad events at start phase
15381 - Add new capabilities:
15382 - can_generate_early_vmstart
15383 - can_generate_early_class_hook_events
15384 - Add new functions:
15385 - GetAllModules
15386 - AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses, AddModuleProvides
15387 - IsModifiableModule
15388 Clarified can_redefine_any_classes, can_retransform_any_classes and IsModifiableClass API to
15389 disallow some implementation defined classes.
15390 </change>
15391 <change date="12 February 2017" version="9.0.0">
15392 Minor update for GetCurrentThread function:
15393 - The function may return NULL in the start phase if the
15394 can_generate_early_vmstart capability is enabled.
15395 </change>
15396 <change date="7 February 2018" version="11.0.0">
15397 Minor update for new class file NestHost and NestMembers attributes:
15398 - Specify that RedefineClasses and RetransformClasses are not allowed
15399 to change the class file NestHost and NestMembers attributes.
15400 - Add new error JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED
15401 that can be returned by RedefineClasses and RetransformClasses.
15402 </change>
15403 <change date="15 June 2018" version="11.0.0">
15404 Support for Low Overhead Heap Sampling:
15405 - Add new capability:
15406 - can_generate_sampled_object_alloc_events
15407 - Add new function:
15408 - SetHeapSamplingInterval
15409 - Add new event type:
15410 - JVMTI_EVENT_SAMPLED_OBJECT_ALLOC
15411 </change>
15412 <change date="20 May 2019" version="13.0.0">
15413 Minor spec update for the capability "can_redefine_any_class".
15414 It now says:
15415 "RedefineClasses can be called on any modifiable class. See IsModifiableClass.
15416 (can_redefine_classes must also be set)"
15417 </change>
15418 <change date="5 June 2019" version="13.0.0">
15419 Minor PopFrame spec update:
15420 - The specified thread must be suspended or must be the current thread.
15421 (It was not allowed to be the current thread before.)
15422 </change>
15423 <change date="10 October 2019" version="14.0.0">
15424 Minor update for new class file Record attribute:
15425 - Specify that RedefineClasses and RetransformClasses are not allowed
15426 to change the class file Record attribute.
15427 </change>
15428 <change date="13 May 2020" version="15.0.0">
15429 Minor update for new class file PermittedSubclasses attribute:
15430 - Specify that RedefineClasses and RetransformClasses are not allowed
15431 to change the class file PermittedSubclasses attribute.
15432 </change>
15433 <change date="15 January 2021" version="17.0.0">
15434 Minor clarification in the section "Agent Shutdown" that says the
15435 implementation may choose to not call the Agent_OnUnload function
15436 if the Agent_OnAttach/Agent_OnAttach_L function reported an error.
15437 </change>
15438 <change date="8 June 2021" version="17.0.0">
15439 Minor update to deprecate Heap functions 1.0.
15440 </change>
15441 <change date="27 April 2022" version="19.0.0">
15442 Support for virtual threads:
15443 - Add new capability:
15444 - can_support_virtual_threads
15445 - Add new functions:
15446 - SuspendAllVirtualThreads
15447 - ResumeAllVirtualThreads
15448 - Add new event types:
15449 - JVMTI_EVENT_VIRTUAL_THREAD_START
15450 - JVMTI_EVENT_VIRTUAL_THREAD_END
15451 - Add new error code:
15452 - JVMTI_ERROR_UNSUPPORTED_OPERATION
15453 </change>
15454 </changehistory>
15455
15456 </specification>
15457 <!-- Keep this comment at the end of the file
15458 Local variables:
15459 mode: sgml
15460 sgml-omittag:t
15461 sgml-shorttag:t
15462 sgml-namecase-general:t
15463 sgml-general-insert-case:lower
15464 sgml-minimize-attributes:nil
15465 sgml-always-quote-attributes:t
15466 sgml-indent-step:2
15467 sgml-indent-data:t
15468 sgml-parent-document:nil
15469 sgml-exposed-tags:nil
15470 sgml-local-catalogs:nil
15471 sgml-local-ecat-files:nil
15472 End:
15473 -->