src/share/vm/prims/jvmti.xml

Print this page




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: