src/hotspot/share/prims/jvmti.xml

rev 49264 : [mq]: event-only
rev 49265 : [mq]: event3
rev 49266 : [mq]: event4
rev 49267 : [mq]: event5
rev 49268 : [mq]: event6

@@ -10351,13 +10351,13 @@
           are enabled then the <eventlink id="ClassFileLoadHook"/> events
           can be posted for classes loaded in the primordial phase.
           See <eventlink id="ClassFileLoadHook"/>.
         </description>
       </capabilityfield>
-      <capabilityfield id="can_sample_heap" since="11">
+      <capabilityfield id="can_generate_sampled_alloc_events" since="11">
         <description>
-          Can sample the heap.
+          Can generate sampled allocation events.
           If this capability is enabled then the heap sampling method
           <functionlink id="SetHeapSamplingRate"></functionlink> can be called and the
           <eventlink id="SampledObjectAlloc"></eventlink> events can be enabled.
         </description>
       </capabilityfield>

@@ -11538,33 +11538,35 @@
     </function>
 
   </category>
 
   <category id="heap_monitoring" label="Heap Monitoring">
-    <function id="SetHeapSamplingRate" phase="any" num="156" since="11">
+    <function id="SetHeapSamplingRate" phase="onload" num="156" since="11">
       <synopsis>Set Heap Sampling Rate</synopsis>
       <description>
-        Set up the allocation system to sample memory at a given
+        Set up the allocation system to sample memory allocations at a given
         average rate via the <paramlink id="sampling_rate"></paramlink> parameter, defined
         by sampling rate in bytes. The
         <paramlink id="sampling_rate"></paramlink> will be the average sampling rate in bytes used throughout
         the execution.
-
-        Setting <paramlink id="sampling_rate"></paramlink> to 0 disables the heap sampling.
+        <p/>
+        Setting <paramlink id="sampling_rate"></paramlink> to 0 samples each allocation supported by the system.
         Combined with a <eventlink id="SampledObjectAlloc"/> event, the Java agent can obtain object allocations with a given sample rate.
       </description>
       <origin>new</origin>
       <capabilities>
-        <required id="can_sample_heap"></required>
+        <required id="can_generate_sampled_alloc_events"></required>
       </capabilities>
       <parameters>
         <param id="sampling_rate">
           <jint/>
           <description>
             The sampling rate in bytes used for sampling. The sampler will use a statistical approach to
             provide in average sampling every <paramlink id="sampling_rate"/> allocated bytes.
-
+            <p/>
+            Passing 0 as a sampling rate provokes a sample per allocation by the system.
+            <p/>
             Note: a low sampling rate, such as sampling every 1024 bytes, will probably incur a high overhead.
             Due to the incurred overhead, the sampler should only be used when knowing it may impact performance.
             On the other hand, sampling however every 1024kB has a far less chance of a high overhead since it will sample
             1024 times less than the 1024-byte sampling.
           </description>

@@ -13558,29 +13560,36 @@
         </description>
       </param>
     </parameters>
   </event>
 
-  <event label="Sampled Object Allocation Trace"
+  <event label="Sampled Object Allocation"
     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11">
     <description>
       Sent when an object is sampled via the
       <internallink id="heap_monitoring"> Heap Sampling Monitoring system </internallink>.
-      Therefore, this event is sent to the user if there is at least one call to
-      <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value.
-
-      The event is sent once the allocation has been done and provides the object, stack trace
+      <p/>
+      By default, the sampling rate used is geometric variable with a 512kb mean, meaning one object every 512k bytes,
+      in average, per thread will
+      provoke a callback. Each thread having its own internal allocation count, each thread will be sampling
+      at the same default rate of 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 to be used by the default sampler.
+      <p/>
+      This event is sent once the allocation has been done and provides the object, stack trace
       for the allocation, the thread allocating, the size of allocation, and class.
       <p/>
       Typical use cases of this system is to determine where most heap allocation are originating from.
       Using this in conjunction of weak references and the function
       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
       stacktrace and which are still live during the execution of the program.
     </description>
     <origin>new</origin>
     <capabilities>
-      <required id="can_sample_heap"></required>
+      <required id="can_generate_sampled_alloc_events"></required>
     </capabilities>
     <parameters>
       <param id="jni_env">
         <outptr>
           <struct>JNIEnv</struct>