jdk-sandbox: comparison src/hotspot/share/prims/jvmti.xml

equal deleted inserted replaced

-:e3bcc86855dd
+:914f305ba6fa
 </capabilityfield>
 <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
 <description>
 Can generate sampled allocation events.
 If this capability is enabled then the heap sampling method
-	  <functionlink id="SetHeapSamplingRate"></functionlink> can be
+	  <functionlink id="SetHeapSamplingInterval"></functionlink> can be
 	  called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
 </description>
 </capabilityfield>
 </capabilitiestypedef>
 </function>
 </category>
 <category id="heap_monitoring" label="Heap Monitoring">
-<function id="SetHeapSamplingRate" phase="onload" num="156" since="11">
+<function id="SetHeapSamplingInterval" phase="onload" num="156" since="11">
-<synopsis>Set Heap Sampling Rate</synopsis>
+<synopsis>Set Heap Sampling Interval</synopsis>
 <description>
 Generate a <eventlink id="SampledObjectAlloc"/> event when objects are allocated.
 	Each thread keeps a counter of bytes allocated. The event will only be generated
-	when that counter exceeds an average of <paramlink id="sampling_rate"></paramlink>
+	when that counter exceeds an average of <paramlink id="sampling_interval"></paramlink>
 	since the last sample.
 <p/>
-Setting <paramlink id="sampling_rate"></paramlink> to 0 will cause an event to be
+Setting <paramlink id="sampling_interval"></paramlink> to 0 will cause an event to be
-	generated by each allocation supported by the system.
+generated by each allocation supported by the system once the new interval is taken into account.
+<p/>
+Note that updating the new sampling interval might take various number of allocations
+to provoke internal data structure updates.  Therefore it is important to
+consider the sampling interval as an average. This includes the interval 0, where events
+might not be generated straight away for each allocation.
 </description>
 <origin>new</origin>
 <capabilities>
 <required id="can_generate_sampled_object_alloc_events"></required>
 </capabilities>
 <parameters>
-<param id="sampling_rate">
+<param id="sampling_interval">
 <jint/>
 <description>
-The sampling rate in bytes. The sampler uses a statistical approach to
+The sampling interval in bytes. The sampler uses a statistical approach to
-generate an event, on average, once for every <paramlink id="sampling_rate"/> bytes of
+generate an event, on average, once for every <paramlink id="sampling_interval"/> bytes of
 	    memory allocated by a given thread.
 <p/>
-Passing 0 as a sampling rate generates a sample for every allocation.
+Once the new sampling interval is taken into account, 0 as a sampling interval will generate
+a sample for every allocation.
 <p/>
-Note: The overhead of this feature is directly correlated with the sampling rate.
+Note: The overhead of this feature is directly correlated with the sampling interval.
-	    A high sampling rate, such as 1024 bytes, will incur a high overhead.
+	    A high sampling interval, such as 1024 bytes, will incur a high overhead.
-	    A lower rate, such as 1024KB, will have a much lower overhead.  Sampling should only
+	    A lower interval, such as 1024KB, will have a much lower overhead.  Sampling should only
 	    be used with an understanding that it may impact performance.
 </description>
 </param>
 </parameters>
 <errors>
 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
-<paramlink id="sampling_rate"></paramlink> is less than zero.
+<paramlink id="sampling_interval"></paramlink> is less than zero.
 </error>
 </errors>
 </function>
 </category>
 <event label="Sampled Object Allocation"
 id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11">
 <description>
 Sent when an allocated object is sampled.
-By default, the sampling rate is a geometric variable with a 512KB mean.
+By default, the sampling interval is set to 512KB. The sampling is semi-random to avoid
+pattern-based bias and provides an approximate overall average interval over long periods of
+sampling.
+<p/>
 Each thread tracks how many bytes it has allocated since it sent the last event.
-When the number of bytes exceeds the sampling rate, it will send another event.
+When the number of bytes exceeds the sampling interval, it will send another event.
 This implies that, on average, one object will be sampled every time a thread has
 allocated 512KB bytes since the last sample.
 <p/>
-Note that this is a geometric variable: it will not sample every 512KB precisely.
+Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
 The goal of this is to ensure high quality sampling even if allocation is
 happening in a fixed pattern (i.e., the same set of objects are being allocated
 every 512KB).
 <p/>
-If another sampling rate is required, the user can call
+If another sampling interval is required, the user can call
-<functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value, representing
+<functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
-the new sampling rate.
+representing the new sampling interval.
 <p/>
 This event is sent once the sampled allocation has been performed.  It provides the object, stack trace
 of the allocation, the thread allocating, the size of allocation, and the object's class.
 <p/>
 A typical use case of this system is to determine where heap allocations originate.

changeset 51138	914f305ba6fa
parent 50741	f132a0f1c2dd
child 51768	9884b717f2ed