9977 </capabilityfield>
9978 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
9979 <description>
9980 Can generate events when the VM is unable to allocate memory from
9981 the <tm>Java</tm> platform heap.
9982 See <eventlink id="ResourceExhausted"/>.
9983 </description>
9984 </capabilityfield>
9985 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
9986 <description>
9987 Can generate events when the VM is unable to create a thread.
9988 See <eventlink id="ResourceExhausted"/>.
9989 </description>
9990 </capabilityfield>
9991 <capabilityfield id="can_generate_early_vmstart" since="9">
9992 <description>
9993 Can generate the <code>VMStart</code> event early.
9994 See <eventlink id="VMStart"/>.
9995 </description>
9996 </capabilityfield>
9997 </capabilitiestypedef>
9998
9999 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10000 <synopsis>Get Potential Capabilities</synopsis>
10001 <description>
10002 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10003 features that can potentially be possessed by this environment
10004 at this time.
10005 The returned capabilities differ from the complete set of capabilities
10006 implemented by the VM in two cases: another environment possesses
10007 capabilities that can only be possessed by one environment, or the
10008 current <functionlink id="GetPhase">phase</functionlink> is live,
10009 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10010 The <functionlink id="AddCapabilities"></functionlink> function
10011 may be used to set any or all or these capabilities.
10012 Currently possessed capabilities are included.
10013 <p/>
10014 Typically this function is used in the <code>OnLoad</code> function.
10015 Some virtual machines may allow a limited set of capabilities to be
10016 added in the live phase.
12387 </outptr>
12388 <description>
12389 The JNI environment of the event (current) thread
12390 </description>
12391 </param>
12392 <param id="thread">
12393 <jthread/>
12394 <description>
12395 Thread generating the class prepare
12396 </description>
12397 </param>
12398 <param id="klass">
12399 <jclass/>
12400 <description>
12401 Class being prepared
12402 </description>
12403 </param>
12404 </parameters>
12405 </event>
12406
12407 <event label="Class File Load Hook" phase="start"
12408 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12409 <description>
12410 This event is sent when the VM obtains class file data,
12411 but before it constructs
12412 the in-memory representation for that class.
12413 This event is also sent when the class is being modified by the
12414 <functionlink id="RetransformClasses"/> function or
12415 the <functionlink id="RedefineClasses"/> function,
12416 called in any <jvmti/> environment.
12417 The agent can instrument
12418 the existing class file data sent by the VM to include profiling/debugging hooks.
12419 See the description of
12420 <internallink id="bci">bytecode instrumentation</internallink>
12421 for usage information.
12422 <p/>
12423 This event may be sent before the VM is initialized (the start
12424 <functionlink id="GetPhase">phase</functionlink>).
12425 Some classes might not be compatible
12426 with the function (eg. ROMized classes) and this event will not be
12427 generated for these classes.
12428 <p/>
12429 The agent must allocate the space for the modified
12430 class file data buffer
12431 using the memory allocation function
12432 <functionlink id="Allocate"></functionlink> because the
12433 VM is responsible for freeing the new class file data buffer
12434 using <functionlink id="Deallocate"></functionlink>.
12435 <p/>
12436 If the agent wishes to modify the class file, it must set
12437 <code>new_class_data</code> to point
12438 to the newly instrumented class file data buffer and set
12439 <code>new_class_data_len</code> to the length of that
12440 buffer before returning
12441 from this call. If no modification is desired, the agent simply
12442 does not set <code>new_class_data</code>. If multiple agents
12443 have enabled this event the results are chained. That is, if
12453 incapable</fieldlink>
12454 environments, in the
12455 order in which they were created
12456 </li>
12457 <li><fieldlink id="can_retransform_classes"
12458 struct="jvmtiCapabilities">retransformation
12459 capable</fieldlink>
12460 environments, in the
12461 order in which they were created
12462 </li>
12463 </ul>
12464 When triggered by <functionlink id="RetransformClasses"/>,
12465 this event is sent only to <fieldlink id="can_retransform_classes"
12466 struct="jvmtiCapabilities">retransformation
12467 capable</fieldlink>
12468 environments.
12469 </description>
12470 <origin>jvmpi</origin>
12471 <capabilities>
12472 <capability id="can_generate_all_class_hook_events"></capability>
12473 </capabilities>
12474 <parameters>
12475 <param id="jni_env">
12476 <outptr>
12477 <struct>JNIEnv</struct>
12478 </outptr>
12479 <description>
12480 The JNI environment of the event (current) thread.
12481 </description>
12482 </param>
12483 <param id="class_being_redefined">
12484 <jclass/>
12485 <description>
12486 The class being
12487 <functionlink id="RedefineClasses">redefined</functionlink> or
12488 <functionlink id="RetransformClasses">retransformed</functionlink>.
12489 <code>NULL</code> if sent by class load.
12490 </description>
12491 </param>
12492 <param id="loader">
12525 </description>
12526 </param>
12527 <param id="new_class_data_len">
12528 <outptr><jint/></outptr>
12529 <description>
12530 Pointer to the length of the new class file data buffer.
12531 </description>
12532 </param>
12533 <param id="new_class_data">
12534 <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12535 <description>
12536 Pointer to the pointer to the instrumented class file data buffer.
12537 </description>
12538 </param>
12539 </parameters>
12540 </event>
12541
12542 <event label="VM Start Event"
12543 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12544 <description>
12545 The VM initialization event signals the start of the VM.
12546 At this time JNI is live but the VM is not yet fully initialized.
12547 Once this event is generated, the agent is free to call any JNI function.
12548 This event signals the beginning of the start phase,
12549 <jvmti/> functions permitted in the start phase may be called.
12550 <p/>
12551 The timing of this event may depend on whether the agent has added the
12552 <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
12553 <code>can_generate_early_vmstart</code></internallink> capability or not.
12554 If the capability has been added then the VM posts the event as early
12555 as possible. The VM is capable of executing bytecode but it may not have
12556 initialized to the point where it can load classes in modules other than
12557 <code>java.base</code>. Agents that do load-time instrumentation in this
12558 phase must take great care when instrumenting code that potentially
12559 executes in this phase. Care should also be taken with JNI
12560 <code>FindClass</code> as it may not be possible to load classes that are
12561 not in the <code>java.base</code> module.
12562 If the capability has not been added then the VM delays posting this
12563 event until it is capable of loading classes in modules other than
12564 <code>java.base</code> or the VM has completed its initialization.
12565 Agents that create more than one JVM TI environment, where the
14401 </change>
14402 <change date="6 August 2006" version="1.1.102">
14403 Add ResourceExhaustedEvent.
14404 </change>
14405 <change date="11 October 2012" version="1.2.2">
14406 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14407 </change>
14408 <change date="19 June 2013" version="1.2.3">
14409 Added support for statically linked agents.
14410 </change>
14411 <change date="20 January 2016" version="9.0.0">
14412 Support for modules:
14413 - The majorversion is 9 now
14414 - The ClassFileLoadHook events are not sent during the primordial phase anymore.
14415 - Add new function GetAllModules
14416 </change>
14417 <change date="17 February 2016" version="9.0.0">
14418 Support for modules:
14419 - Add new capability can_generate_early_vmstart
14420 - Allow CompiledMethodLoad events at start phase
14421 </change>
14422 </changehistory>
14423
14424 </specification>
14425 <!-- Keep this comment at the end of the file
14426 Local variables:
14427 mode: sgml
14428 sgml-omittag:t
14429 sgml-shorttag:t
14430 sgml-namecase-general:t
14431 sgml-general-insert-case:lower
14432 sgml-minimize-attributes:nil
14433 sgml-always-quote-attributes:t
14434 sgml-indent-step:2
14435 sgml-indent-data:t
14436 sgml-parent-document:nil
14437 sgml-exposed-tags:nil
14438 sgml-local-catalogs:nil
14439 sgml-local-ecat-files:nil
14440 End:
|
9977 </capabilityfield>
9978 <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
9979 <description>
9980 Can generate events when the VM is unable to allocate memory from
9981 the <tm>Java</tm> platform heap.
9982 See <eventlink id="ResourceExhausted"/>.
9983 </description>
9984 </capabilityfield>
9985 <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
9986 <description>
9987 Can generate events when the VM is unable to create a thread.
9988 See <eventlink id="ResourceExhausted"/>.
9989 </description>
9990 </capabilityfield>
9991 <capabilityfield id="can_generate_early_vmstart" since="9">
9992 <description>
9993 Can generate the <code>VMStart</code> event early.
9994 See <eventlink id="VMStart"/>.
9995 </description>
9996 </capabilityfield>
9997 <capabilityfield id="can_generate_early_class_hook_events" since="9">
9998 <description>
9999 Can generate the <eventlink id="ClassFileLoadHook"/> events early.
10000 If this capability and
10001 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
10002 ><code>can_generate_all_class_hook_events</code></internallink>
10003 are enabled then the <eventlink id="ClassFileLoadHook"/> events
10004 could be posted for classes loaded in the primordial phase.
10005 See <eventlink id="ClassFileLoadHook"/>.
10006 </description>
10007 </capabilityfield>
10008 </capabilitiestypedef>
10009
10010 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10011 <synopsis>Get Potential Capabilities</synopsis>
10012 <description>
10013 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10014 features that can potentially be possessed by this environment
10015 at this time.
10016 The returned capabilities differ from the complete set of capabilities
10017 implemented by the VM in two cases: another environment possesses
10018 capabilities that can only be possessed by one environment, or the
10019 current <functionlink id="GetPhase">phase</functionlink> is live,
10020 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10021 The <functionlink id="AddCapabilities"></functionlink> function
10022 may be used to set any or all or these capabilities.
10023 Currently possessed capabilities are included.
10024 <p/>
10025 Typically this function is used in the <code>OnLoad</code> function.
10026 Some virtual machines may allow a limited set of capabilities to be
10027 added in the live phase.
12398 </outptr>
12399 <description>
12400 The JNI environment of the event (current) thread
12401 </description>
12402 </param>
12403 <param id="thread">
12404 <jthread/>
12405 <description>
12406 Thread generating the class prepare
12407 </description>
12408 </param>
12409 <param id="klass">
12410 <jclass/>
12411 <description>
12412 Class being prepared
12413 </description>
12414 </param>
12415 </parameters>
12416 </event>
12417
12418 <event label="Class File Load Hook" phase="any"
12419 id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12420 <description>
12421 This event is sent when the VM obtains class file data,
12422 but before it constructs
12423 the in-memory representation for that class.
12424 This event is also sent when the class is being modified by the
12425 <functionlink id="RetransformClasses"/> function or
12426 the <functionlink id="RedefineClasses"/> function,
12427 called in any <jvmti/> environment.
12428 The agent can instrument
12429 the existing class file data sent by the VM to include profiling/debugging hooks.
12430 See the description of
12431 <internallink id="bci">bytecode instrumentation</internallink>
12432 for usage information.
12433 <p/>
12434 The timing of this event may depend on whether the agent has added the
12435 <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
12436 <code>can_generate_early_class_hook_events</code></internallink>
12437 capability or not.
12438 If the capability has been added then the VM posts the events in the primordial phase.
12439 Otherwise, this event may be sent before the VM is initialized (the start
12440 <functionlink id="GetPhase">phase</functionlink>).
12441 Some classes might not be compatible
12442 with the function (eg. ROMized classes) and this event will not be
12443 generated for these classes.
12444 <p/>
12445 The agent must allocate the space for the modified
12446 class file data buffer
12447 using the memory allocation function
12448 <functionlink id="Allocate"></functionlink> because the
12449 VM is responsible for freeing the new class file data buffer
12450 using <functionlink id="Deallocate"></functionlink>.
12451 <p/>
12452 If the agent wishes to modify the class file, it must set
12453 <code>new_class_data</code> to point
12454 to the newly instrumented class file data buffer and set
12455 <code>new_class_data_len</code> to the length of that
12456 buffer before returning
12457 from this call. If no modification is desired, the agent simply
12458 does not set <code>new_class_data</code>. If multiple agents
12459 have enabled this event the results are chained. That is, if
12469 incapable</fieldlink>
12470 environments, in the
12471 order in which they were created
12472 </li>
12473 <li><fieldlink id="can_retransform_classes"
12474 struct="jvmtiCapabilities">retransformation
12475 capable</fieldlink>
12476 environments, in the
12477 order in which they were created
12478 </li>
12479 </ul>
12480 When triggered by <functionlink id="RetransformClasses"/>,
12481 this event is sent only to <fieldlink id="can_retransform_classes"
12482 struct="jvmtiCapabilities">retransformation
12483 capable</fieldlink>
12484 environments.
12485 </description>
12486 <origin>jvmpi</origin>
12487 <capabilities>
12488 <capability id="can_generate_all_class_hook_events"></capability>
12489 <capability id="can_generate_early_class_hook_events"></capability>
12490 </capabilities>
12491 <parameters>
12492 <param id="jni_env">
12493 <outptr>
12494 <struct>JNIEnv</struct>
12495 </outptr>
12496 <description>
12497 The JNI environment of the event (current) thread.
12498 </description>
12499 </param>
12500 <param id="class_being_redefined">
12501 <jclass/>
12502 <description>
12503 The class being
12504 <functionlink id="RedefineClasses">redefined</functionlink> or
12505 <functionlink id="RetransformClasses">retransformed</functionlink>.
12506 <code>NULL</code> if sent by class load.
12507 </description>
12508 </param>
12509 <param id="loader">
12542 </description>
12543 </param>
12544 <param id="new_class_data_len">
12545 <outptr><jint/></outptr>
12546 <description>
12547 Pointer to the length of the new class file data buffer.
12548 </description>
12549 </param>
12550 <param id="new_class_data">
12551 <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12552 <description>
12553 Pointer to the pointer to the instrumented class file data buffer.
12554 </description>
12555 </param>
12556 </parameters>
12557 </event>
12558
12559 <event label="VM Start Event"
12560 id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12561 <description>
12562 The VM start event signals the start of the VM.
12563 At this time JNI is live but the VM is not yet fully initialized.
12564 Once this event is generated, the agent is free to call any JNI function.
12565 This event signals the beginning of the start phase,
12566 <jvmti/> functions permitted in the start phase may be called.
12567 <p/>
12568 The timing of this event may depend on whether the agent has added the
12569 <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
12570 <code>can_generate_early_vmstart</code></internallink> capability or not.
12571 If the capability has been added then the VM posts the event as early
12572 as possible. The VM is capable of executing bytecode but it may not have
12573 initialized to the point where it can load classes in modules other than
12574 <code>java.base</code>. Agents that do load-time instrumentation in this
12575 phase must take great care when instrumenting code that potentially
12576 executes in this phase. Care should also be taken with JNI
12577 <code>FindClass</code> as it may not be possible to load classes that are
12578 not in the <code>java.base</code> module.
12579 If the capability has not been added then the VM delays posting this
12580 event until it is capable of loading classes in modules other than
12581 <code>java.base</code> or the VM has completed its initialization.
12582 Agents that create more than one JVM TI environment, where the
14418 </change>
14419 <change date="6 August 2006" version="1.1.102">
14420 Add ResourceExhaustedEvent.
14421 </change>
14422 <change date="11 October 2012" version="1.2.2">
14423 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14424 </change>
14425 <change date="19 June 2013" version="1.2.3">
14426 Added support for statically linked agents.
14427 </change>
14428 <change date="20 January 2016" version="9.0.0">
14429 Support for modules:
14430 - The majorversion is 9 now
14431 - The ClassFileLoadHook events are not sent during the primordial phase anymore.
14432 - Add new function GetAllModules
14433 </change>
14434 <change date="17 February 2016" version="9.0.0">
14435 Support for modules:
14436 - Add new capability can_generate_early_vmstart
14437 - Allow CompiledMethodLoad events at start phase
14438 </change>
14439 <change date="14 April 2016" version="9.0.0">
14440 Support for modules:
14441 - Add new capability can_generate_early_class_hook_events
14442 </change>
14443 </changehistory>
14444
14445 </specification>
14446 <!-- Keep this comment at the end of the file
14447 Local variables:
14448 mode: sgml
14449 sgml-omittag:t
14450 sgml-shorttag:t
14451 sgml-namecase-general:t
14452 sgml-general-insert-case:lower
14453 sgml-minimize-attributes:nil
14454 sgml-always-quote-attributes:t
14455 sgml-indent-step:2
14456 sgml-indent-data:t
14457 sgml-parent-document:nil
14458 sgml-exposed-tags:nil
14459 sgml-local-catalogs:nil
14460 sgml-local-ecat-files:nil
14461 End:
|