--- a/src/hotspot/share/prims/jvmti.xml	Tue Jul 17 17:52:03 2018 -0700
+++ b/src/hotspot/share/prims/jvmti.xml	Tue Jul 17 19:59:38 2018 -0700
@@ -10369,7 +10369,7 @@
         <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>
@@ -11552,41 +11552,47 @@
   </category>
 
   <category id="heap_monitoring" label="Heap Monitoring">
-    <function id="SetHeapSamplingRate" phase="onload" num="156" since="11">
-      <synopsis>Set Heap Sampling Rate</synopsis>
+    <function id="SetHeapSamplingInterval" phase="onload" num="156" since="11">
+      <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
-	generated by each allocation supported by the system.
+        Setting <paramlink id="sampling_interval"></paramlink> to 0 will cause an event to be
+        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
-            generate an event, on average, once for every <paramlink id="sampling_rate"/> bytes of
+            The sampling interval in bytes. The sampler uses a statistical approach to
+            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. 
-	    A high sampling rate, such as 1024 bytes, will incur a high overhead.
-	    A lower rate, such as 1024KB, will have a much lower overhead.  Sampling should only
+            Note: The overhead of this feature is directly correlated with the sampling interval.
+	    A high sampling interval, such as 1024 bytes, will incur a high overhead.
+	    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>
@@ -13586,20 +13592,23 @@
     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
-      <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value, representing
-      the new sampling rate.
+      If another sampling interval is required, the user can call
+      <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
+      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.