src/hotspot/share/prims/jvmti.xml

rev 49244 : [mq]: event-only
rev 49245 : [mq]: event3
rev 49246 : [mq]: event4
rev 49247 : [mq]: event5

@@ -10351,10 +10351,18 @@
           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">
+        <description>
+          Can sample the heap.
+          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>
     </capabilitiestypedef>
 
     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
       <synopsis>Get Potential Capabilities</synopsis>
       <description>

@@ -11529,10 +11537,49 @@
       </errors>
     </function>
 
   </category>
 
+  <category id="heap_monitoring" label="Heap Monitoring">
+    <function id="SetHeapSamplingRate" phase="any" num="156" since="11">
+      <synopsis>Set Heap Sampling Rate</synopsis>
+      <description>
+        Set up the allocation system to sample memory 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.
+        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>
+      </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.
+
+            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>
+        </param>
+      </parameters>
+      <errors>
+        <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+          <paramlink id="sampling_rate"></paramlink> is less than zero.
+        </error>
+      </errors>
+    </function>
+  </category>
+
 </functionsection>
 
 <errorsection label="Error Reference">
   <intro>
     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.

@@ -13493,11 +13540,67 @@
           </description>
       </param>
       <param id="object">
         <jobject/>
           <description>
-            JNI local reference to the object that was allocated
+            JNI local reference to the object that was allocated.
+          </description>
+      </param>
+      <param id="object_klass">
+        <jclass/>
+          <description>
+            JNI local reference to the class of the object.
+          </description>
+      </param>
+      <param id="size">
+        <jlong/>
+        <description>
+            Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
+        </description>
+      </param>
+    </parameters>
+  </event>
+
+  <event label="Sampled Object Allocation Trace"
+    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
+      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>
+    </capabilities>
+    <parameters>
+      <param id="jni_env">
+        <outptr>
+          <struct>JNIEnv</struct>
+        </outptr>
+        <description>
+          The JNI environment of the event (current) thread.
+        </description>
+      </param>
+      <param id="thread">
+        <jthread/>
+        <description>
+          Thread allocating the object.
+        </description>
+      </param>
+      <param id="object">
+        <jobject/>
+        <description>
+          JNI local reference to the object that was allocated.
           </description>
       </param>
       <param id="object_klass">
         <jclass/>
           <description>