< prev index next >

src/hotspot/share/prims/jvmti.xml

Print this page
rev 49244 : [mq]: event-only
rev 49245 : [mq]: event3
rev 49246 : [mq]: event4
rev 49247 : [mq]: event5


10340         <description>
10341           Can generate the <code>VMStart</code> event early.
10342           See <eventlink id="VMStart"/>.
10343         </description>
10344       </capabilityfield>
10345       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10346         <description>
10347           Can generate the <eventlink id="ClassFileLoadHook"/> events
10348           in the primordial phase. If this capability and
10349           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10350           <code>can_generate_all_class_hook_events</code></internallink>
10351           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10352           can be posted for classes loaded in the primordial phase.
10353           See <eventlink id="ClassFileLoadHook"/>.
10354         </description>
10355       </capabilityfield>
10356       <capabilityfield id="can_sample_heap" since="11">
10357         <description>
10358           Can sample the heap.
10359           If this capability is enabled then the heap sampling method
10360           <functionlink id="SetTlabHeapSampling"></functionlink> can be called and the
10361           <eventlink id="SampledObjectAlloc"></eventlink> events can be enabled.
10362         </description>
10363       </capabilityfield>
10364     </capabilitiestypedef>
10365 
10366     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10367       <synopsis>Get Potential Capabilities</synopsis>
10368       <description>
10369         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10370         features that can potentially be possessed by this environment
10371         at this time.
10372         The returned capabilities differ from the complete set of capabilities
10373         implemented by the VM in two cases: another environment possesses
10374         capabilities that can only be possessed by one environment, or the
10375         current <functionlink id="GetPhase">phase</functionlink> is live,
10376         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10377         The <functionlink id="AddCapabilities"></functionlink> function
10378         may be used to set any or all or these capabilities.
10379         Currently possessed capabilities are included.
10380         <p/>


11523         </constants>
11524       </description>
11525       <origin>new</origin>
11526       <capabilities>
11527       </capabilities>
11528       <parameters>
11529         <param id="format_ptr">
11530           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11531           <description>
11532             On return, points to the format identifier for <code>jlocation</code> values.
11533           </description>
11534         </param>
11535       </parameters>
11536       <errors>
11537       </errors>
11538     </function>
11539 
11540   </category>
11541 
11542   <category id="heap_monitoring" label="Heap Monitoring">
11543     <function id="SetTlabHeapSampling" phase="any" num="156" since="11">
11544       <synopsis>Set TLAB Heap Sampling</synopsis>
11545       <description>
11546         Set up the TLAB allocation system to sample memory by forcing slow path execution at a given
11547         average rate via the <paramlink id="monitoring_rate"></paramlink>. The
11548         <paramlink id="monitoring_rate"></paramlink> will be the average sampling rate used throughout

11549         the execution.
11550 
11551         Setting <paramlink id="monitoring_rate"></paramlink> to 0 disables the TLAB heap sampling.
11552         Combined with a <eventlink id="SampledObjectAlloc"/> event, the Java agent can obtain object allocations with a given sample rate.
11553       </description>
11554       <origin>new</origin>
11555       <capabilities>
11556         <required id="can_sample_heap"></required>
11557       </capabilities>
11558       <parameters>
11559         <param id="monitoring_rate">
11560           <jint/>
11561           <description>
11562             The monitoring rate in bytes used for sampling. The sampler will use a statistical approach to
11563             provide in average sampling every <paramlink id="monitoring_rate"/> allocated bytes.
11564 
11565             Note: a low monitoring rate, such as sampling every 1024 bytes, will probably incur a high overhead.
11566             Due to the incurred overhead, the sampler should only be used when knowing it may impact performance.
11567             On the other hand, sampling however every 1024kB has a far less chance of a high overhead since it will sample
11568             1024 times less than the 1024-byte sampling.
11569           </description>
11570         </param>
11571       </parameters>
11572       <errors>
11573         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11574           <paramlink id="monitoring_rate"></paramlink> is less than zero.
11575         </error>
11576         <error id="JVMTI_ERROR_TLAB_DISABLED">
11577           Calling this method without TLAB.
11578         </error>
11579       </errors>
11580     </function>
11581   </category>
11582 
11583 </functionsection>
11584 
11585 <errorsection label="Error Reference">
11586   <intro>
11587     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11588     <p/>
11589     It is the responsibility of the agent to call <jvmti/> functions with
11590     valid parameters and in the proper context (calling thread is attached,
11591     phase is correct, etc.).
11592     Detecting some error conditions may be difficult, inefficient, or
11593     impossible for an implementation.
11594     The errors listed in
11595     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11596     must be detected by the implementation.
11597     All other errors represent the recommended response to the error


11771     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11772       A direct superclass is different for the new class
11773       version, or the set of directly implemented
11774       interfaces is different.
11775     </errorid>
11776     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11777       A new class version does not declare a method
11778       declared in the old class version.
11779     </errorid>
11780     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11781       The class name defined in the new class file is
11782       different from the name in the old class object.
11783     </errorid>
11784     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11785       A new class version has different modifiers.
11786     </errorid>
11787     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11788       A method in the new class version has different modifiers
11789       than its counterpart in the old class version.
11790     </errorid>
11791     <errorid id="JVMTI_ERROR_TLAB_DISABLED" num="72">
11792       The Thread Local Allocation Buffer system is disabled and the method requires it enabled.
11793     </errorid>
11794   </errorcategory>
11795 </errorsection>
11796 
11797 <eventsection label="Events">
11798   <intro label="Handling Events" id="eventIntro">
11799     Agents can be informed of many events that occur in application
11800     programs.
11801     <p/>
11802     To handle events, designate a set of callback functions with
11803     <functionlink id="SetEventCallbacks"></functionlink>.
11804     For each event the corresponding callback function will be
11805     called.
11806     Arguments to the callback function provide additional
11807     information about the event.
11808     <p/>
11809     The callback function is usually called from within an application
11810     thread. The <jvmti/> implementation does not
11811     queue events in any way. This means
11812     that event callback functions must be written
11813     carefully. Here are some general guidelines. See


13549           <description>
13550             JNI local reference to the object that was allocated.
13551           </description>
13552       </param>
13553       <param id="object_klass">
13554         <jclass/>
13555           <description>
13556             JNI local reference to the class of the object.
13557           </description>
13558       </param>
13559       <param id="size">
13560         <jlong/>
13561         <description>
13562             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13563         </description>
13564       </param>
13565     </parameters>
13566   </event>
13567 
13568   <event label="Sampled Object Allocation Trace"
13569     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86">
13570     <description>
13571       Sent when an object is sampled via the
13572       <internallink id="heap_monitoring"> Heap Sampling Monitoring system </internallink>.
13573       Therefore, this event is sent to the user if there is at least one call to
13574       <functionlink id="SetTlabHeapSampling"></functionlink> with a strictly positive integer value.
13575 
13576       The event is sent once the allocation has been done and provides the object, stack trace
13577       for the allocation, the thread allocating, the size of allocation, and class.
13578       <p/>
13579       Typical use cases of this system is to determine where most heap allocation are originating from.
13580       Using this in conjunction of weak references and the function
13581       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
13582       stacktrace and which are still live during the execution of the program.
13583     </description>
13584     <origin>new</origin>
13585     <capabilities>
13586       <required id="can_sample_heap"></required>
13587     </capabilities>
13588     <parameters>
13589       <param id="jni_env">
13590         <outptr>
13591           <struct>JNIEnv</struct>
13592         </outptr>
13593         <description>
13594           The JNI environment of the event (current) thread.




10340         <description>
10341           Can generate the <code>VMStart</code> event early.
10342           See <eventlink id="VMStart"/>.
10343         </description>
10344       </capabilityfield>
10345       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10346         <description>
10347           Can generate the <eventlink id="ClassFileLoadHook"/> events
10348           in the primordial phase. If this capability and
10349           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10350           <code>can_generate_all_class_hook_events</code></internallink>
10351           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10352           can be posted for classes loaded in the primordial phase.
10353           See <eventlink id="ClassFileLoadHook"/>.
10354         </description>
10355       </capabilityfield>
10356       <capabilityfield id="can_sample_heap" since="11">
10357         <description>
10358           Can sample the heap.
10359           If this capability is enabled then the heap sampling method
10360           <functionlink id="SetHeapSamplingRate"></functionlink> can be called and the
10361           <eventlink id="SampledObjectAlloc"></eventlink> events can be enabled.
10362         </description>
10363       </capabilityfield>
10364     </capabilitiestypedef>
10365 
10366     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10367       <synopsis>Get Potential Capabilities</synopsis>
10368       <description>
10369         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10370         features that can potentially be possessed by this environment
10371         at this time.
10372         The returned capabilities differ from the complete set of capabilities
10373         implemented by the VM in two cases: another environment possesses
10374         capabilities that can only be possessed by one environment, or the
10375         current <functionlink id="GetPhase">phase</functionlink> is live,
10376         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10377         The <functionlink id="AddCapabilities"></functionlink> function
10378         may be used to set any or all or these capabilities.
10379         Currently possessed capabilities are included.
10380         <p/>


11523         </constants>
11524       </description>
11525       <origin>new</origin>
11526       <capabilities>
11527       </capabilities>
11528       <parameters>
11529         <param id="format_ptr">
11530           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11531           <description>
11532             On return, points to the format identifier for <code>jlocation</code> values.
11533           </description>
11534         </param>
11535       </parameters>
11536       <errors>
11537       </errors>
11538     </function>
11539 
11540   </category>
11541 
11542   <category id="heap_monitoring" label="Heap Monitoring">
11543     <function id="SetHeapSamplingRate" phase="any" num="156" since="11">
11544       <synopsis>Set Heap Sampling Rate</synopsis>
11545       <description>
11546         Set up the allocation system to sample memory at a given
11547         average rate via the <paramlink id="sampling_rate"></paramlink> parameter, defined
11548         by sampling rate in bytes. The
11549         <paramlink id="sampling_rate"></paramlink> will be the average sampling rate in bytes used throughout
11550         the execution.
11551 
11552         Setting <paramlink id="sampling_rate"></paramlink> to 0 disables the heap sampling.
11553         Combined with a <eventlink id="SampledObjectAlloc"/> event, the Java agent can obtain object allocations with a given sample rate.
11554       </description>
11555       <origin>new</origin>
11556       <capabilities>
11557         <required id="can_sample_heap"></required>
11558       </capabilities>
11559       <parameters>
11560         <param id="sampling_rate">
11561           <jint/>
11562           <description>
11563             The sampling rate in bytes used for sampling. The sampler will use a statistical approach to
11564             provide in average sampling every <paramlink id="sampling_rate"/> allocated bytes.
11565 
11566             Note: a low sampling rate, such as sampling every 1024 bytes, will probably incur a high overhead.
11567             Due to the incurred overhead, the sampler should only be used when knowing it may impact performance.
11568             On the other hand, sampling however every 1024kB has a far less chance of a high overhead since it will sample
11569             1024 times less than the 1024-byte sampling.
11570           </description>
11571         </param>
11572       </parameters>
11573       <errors>
11574         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11575           <paramlink id="sampling_rate"></paramlink> is less than zero.



11576         </error>
11577       </errors>
11578     </function>
11579   </category>
11580 
11581 </functionsection>
11582 
11583 <errorsection label="Error Reference">
11584   <intro>
11585     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11586     <p/>
11587     It is the responsibility of the agent to call <jvmti/> functions with
11588     valid parameters and in the proper context (calling thread is attached,
11589     phase is correct, etc.).
11590     Detecting some error conditions may be difficult, inefficient, or
11591     impossible for an implementation.
11592     The errors listed in
11593     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11594     must be detected by the implementation.
11595     All other errors represent the recommended response to the error


11769     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11770       A direct superclass is different for the new class
11771       version, or the set of directly implemented
11772       interfaces is different.
11773     </errorid>
11774     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11775       A new class version does not declare a method
11776       declared in the old class version.
11777     </errorid>
11778     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11779       The class name defined in the new class file is
11780       different from the name in the old class object.
11781     </errorid>
11782     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11783       A new class version has different modifiers.
11784     </errorid>
11785     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11786       A method in the new class version has different modifiers
11787       than its counterpart in the old class version.
11788     </errorid>



11789   </errorcategory>
11790 </errorsection>
11791 
11792 <eventsection label="Events">
11793   <intro label="Handling Events" id="eventIntro">
11794     Agents can be informed of many events that occur in application
11795     programs.
11796     <p/>
11797     To handle events, designate a set of callback functions with
11798     <functionlink id="SetEventCallbacks"></functionlink>.
11799     For each event the corresponding callback function will be
11800     called.
11801     Arguments to the callback function provide additional
11802     information about the event.
11803     <p/>
11804     The callback function is usually called from within an application
11805     thread. The <jvmti/> implementation does not
11806     queue events in any way. This means
11807     that event callback functions must be written
11808     carefully. Here are some general guidelines. See


13544           <description>
13545             JNI local reference to the object that was allocated.
13546           </description>
13547       </param>
13548       <param id="object_klass">
13549         <jclass/>
13550           <description>
13551             JNI local reference to the class of the object.
13552           </description>
13553       </param>
13554       <param id="size">
13555         <jlong/>
13556         <description>
13557             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13558         </description>
13559       </param>
13560     </parameters>
13561   </event>
13562 
13563   <event label="Sampled Object Allocation Trace"
13564     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11">
13565     <description>
13566       Sent when an object is sampled via the
13567       <internallink id="heap_monitoring"> Heap Sampling Monitoring system </internallink>.
13568       Therefore, this event is sent to the user if there is at least one call to
13569       <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value.
13570 
13571       The event is sent once the allocation has been done and provides the object, stack trace
13572       for the allocation, the thread allocating, the size of allocation, and class.
13573       <p/>
13574       Typical use cases of this system is to determine where most heap allocation are originating from.
13575       Using this in conjunction of weak references and the function
13576       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
13577       stacktrace and which are still live during the execution of the program.
13578     </description>
13579     <origin>new</origin>
13580     <capabilities>
13581       <required id="can_sample_heap"></required>
13582     </capabilities>
13583     <parameters>
13584       <param id="jni_env">
13585         <outptr>
13586           <struct>JNIEnv</struct>
13587         </outptr>
13588         <description>
13589           The JNI environment of the event (current) thread.


< prev index next >