< prev index next >

src/hotspot/share/prims/jvmti.xml

Print this page
rev 50392 : JEP 331


10336           See <eventlink id="ResourceExhausted"/>.
10337         </description>
10338       </capabilityfield>
10339       <capabilityfield id="can_generate_early_vmstart" since="9">
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     </capabilitiestypedef>
10357 
10358     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10359       <synopsis>Get Potential Capabilities</synopsis>
10360       <description>
10361         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10362         features that can potentially be possessed by this environment
10363         at this time.
10364         The returned capabilities differ from the complete set of capabilities
10365         implemented by the VM in two cases: another environment possesses
10366         capabilities that can only be possessed by one environment, or the
10367         current <functionlink id="GetPhase">phase</functionlink> is live,
10368         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10369         The <functionlink id="AddCapabilities"></functionlink> function
10370         may be used to set any or all or these capabilities.
10371         Currently possessed capabilities are included.
10372         <p/>
10373         Typically this function is used in the <code>OnLoad</code> function.
10374         Some virtual machines may allow a limited set of capabilities to be
10375         added in the live phase.


11514           </constant>
11515         </constants>
11516       </description>
11517       <origin>new</origin>
11518       <capabilities>
11519       </capabilities>
11520       <parameters>
11521         <param id="format_ptr">
11522           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11523           <description>
11524             On return, points to the format identifier for <code>jlocation</code> values.
11525           </description>
11526         </param>
11527       </parameters>
11528       <errors>
11529       </errors>
11530     </function>
11531 
11532   </category>
11533 









































11534 </functionsection>
11535 
11536 <errorsection label="Error Reference">
11537   <intro>
11538     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11539     <p/>
11540     It is the responsibility of the agent to call <jvmti/> functions with
11541     valid parameters and in the proper context (calling thread is attached,
11542     phase is correct, etc.).
11543     Detecting some error conditions may be difficult, inefficient, or
11544     impossible for an implementation.
11545     The errors listed in
11546     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11547     must be detected by the implementation.
11548     All other errors represent the recommended response to the error
11549     condition.
11550   </intro>
11551 
11552   <errorcategory id="universal-error" label="Universal Errors">
11553     <intro>


13478       <required id="can_generate_vm_object_alloc_events"></required>
13479     </capabilities>
13480     <parameters>
13481       <param id="jni_env">
13482         <outptr>
13483           <struct>JNIEnv</struct>
13484         </outptr>
13485           <description>
13486             The JNI environment of the event (current) thread
13487           </description>
13488       </param>
13489       <param id="thread">
13490         <jthread/>
13491           <description>
13492             Thread allocating the object.
13493           </description>
13494       </param>
13495       <param id="object">
13496         <jobject/>
13497           <description>
13498             JNI local reference to the object that was allocated



































































13499           </description>
13500       </param>
13501       <param id="object_klass">
13502         <jclass/>
13503           <description>
13504             JNI local reference to the class of the object
13505           </description>
13506       </param>
13507       <param id="size">
13508         <jlong/>
13509         <description>
13510             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13511         </description>
13512       </param>
13513     </parameters>
13514   </event>
13515 
13516   <event label="Object Free"
13517          id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13518     <description>




10336           See <eventlink id="ResourceExhausted"/>.
10337         </description>
10338       </capabilityfield>
10339       <capabilityfield id="can_generate_early_vmstart" since="9">
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_generate_sampled_object_alloc_events" since="11">
10357         <description>
10358           Can generate sampled allocation events.
10359           If this capability is enabled then the heap sampling method
10360           <functionlink id="SetHeapSamplingRate"></functionlink> can be
10361           called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
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/>
10381         Typically this function is used in the <code>OnLoad</code> function.
10382         Some virtual machines may allow a limited set of capabilities to be
10383         added in the live phase.


11522           </constant>
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="onload" num="156" since="11">
11544       <synopsis>Set Heap Sampling Rate</synopsis>
11545       <description>
11546         Generate a <eventlink id="SampledObjectAlloc"/> event when objects are allocated.
11547         Each thread keeps a counter of bytes allocated. The event will only be generated
11548         when that counter exceeds an average of <paramlink id="sampling_rate"></paramlink>
11549         since the last sample.
11550         <p/>
11551         Setting <paramlink id="sampling_rate"></paramlink> to 0 will cause an event to be
11552         generated by each allocation supported by the system.
11553       </description>
11554       <origin>new</origin>
11555       <capabilities>
11556         <required id="can_generate_sampled_object_alloc_events"></required>
11557       </capabilities>
11558       <parameters>
11559         <param id="sampling_rate">
11560           <jint/>
11561           <description>
11562             The sampling rate in bytes. The sampler uses a statistical approach to
11563             generate an event, on average, once for every <paramlink id="sampling_rate"/> bytes of
11564             memory allocated by a given thread.
11565             <p/>
11566             Passing 0 as a sampling rate generates a sample for every allocation.
11567             <p/>
11568             Note: The overhead of this feature is directly correlated with the sampling rate. 
11569             A high sampling rate, such as 1024 bytes, will incur a high overhead.
11570             A lower rate, such as 1024KB, will have a much lower overhead.  Sampling should only
11571             be used with an understanding that it may impact performance.
11572           </description>
11573         </param>
11574       </parameters>
11575       <errors>
11576         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11577           <paramlink id="sampling_rate"></paramlink> is less than zero.
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
11598     condition.
11599   </intro>
11600 
11601   <errorcategory id="universal-error" label="Universal Errors">
11602     <intro>


13527       <required id="can_generate_vm_object_alloc_events"></required>
13528     </capabilities>
13529     <parameters>
13530       <param id="jni_env">
13531         <outptr>
13532           <struct>JNIEnv</struct>
13533         </outptr>
13534           <description>
13535             The JNI environment of the event (current) thread
13536           </description>
13537       </param>
13538       <param id="thread">
13539         <jthread/>
13540           <description>
13541             Thread allocating the object.
13542           </description>
13543       </param>
13544       <param id="object">
13545         <jobject/>
13546           <description>
13547             JNI local reference to the object that was allocated.
13548           </description>
13549       </param>
13550       <param id="object_klass">
13551         <jclass/>
13552           <description>
13553             JNI local reference to the class of the object.
13554           </description>
13555       </param>
13556       <param id="size">
13557         <jlong/>
13558         <description>
13559             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13560         </description>
13561       </param>
13562     </parameters>
13563   </event>
13564 
13565   <event label="Sampled Object Allocation"
13566     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11">
13567     <description>
13568       Sent when an allocated object is sampled.
13569       By default, the sampling rate is a geometric variable with a 512KB mean.  
13570       Each thread tracks how many bytes it has allocated since it sent the last event.
13571       When the number of bytes exceeds the sampling rate, it will send another event.
13572       This implies that, on average, one object will be sampled every time a thread has
13573       allocated 512KB bytes since the last sample.
13574       <p/>
13575       Note that this is a geometric variable: it will not sample every 512KB precisely.
13576       The goal of this is to ensure high quality sampling even if allocation is
13577       happening in a fixed pattern (i.e., the same set of objects are being allocated
13578       every 512KB).
13579       <p/>
13580       If another sampling rate is required, the user can call
13581       <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value, representing
13582       the new sampling rate.
13583       <p/>
13584       This event is sent once the sampled allocation has been performed.  It provides the object, stack trace
13585       of the allocation, the thread allocating, the size of allocation, and the object's class.
13586       <p/>
13587       A typical use case of this system is to determine where heap allocations originate.
13588       In conjunction with weak references and the function
13589       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
13590       stack trace, and which are still live during the execution of the program.
13591     </description>
13592     <origin>new</origin>
13593     <capabilities>
13594       <required id="can_generate_sampled_object_alloc_events"></required>
13595     </capabilities>
13596     <parameters>
13597       <param id="jni_env">
13598         <outptr>
13599           <struct>JNIEnv</struct>
13600         </outptr>
13601         <description>
13602           The JNI environment of the event (current) thread.
13603         </description>
13604       </param>
13605       <param id="thread">
13606         <jthread/>
13607         <description>
13608           Thread allocating the object.
13609         </description>
13610       </param>
13611       <param id="object">
13612         <jobject/>
13613         <description>
13614           JNI local reference to the object that was allocated.
13615         </description>
13616       </param>
13617       <param id="object_klass">
13618         <jclass/>
13619         <description>
13620           JNI local reference to the class of the object
13621         </description>
13622       </param>
13623       <param id="size">
13624         <jlong/>
13625         <description>
13626           Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13627         </description>
13628       </param>
13629     </parameters>
13630   </event>
13631 
13632   <event label="Object Free"
13633         id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13634     <description>


< prev index next >