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>

 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>

 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