< prev index next >


Print this page
rev 50392 : JEP 331

@@ -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"/>.
+      <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
+          called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
+        </description>
+      </capabilityfield>
     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
       <synopsis>Get Potential Capabilities</synopsis>

@@ -11529,10 +11537,51 @@
+  <category id="heap_monitoring" label="Heap Monitoring">
+    <function id="SetHeapSamplingRate" phase="onload" num="156" since="11">
+      <synopsis>Set Heap Sampling Rate</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>
+        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.
+      </description>
+      <origin>new</origin>
+      <capabilities>
+        <required id="can_generate_sampled_object_alloc_events"></required>
+      </capabilities>
+      <parameters>
+        <param id="sampling_rate">
+          <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
+            memory allocated by a given thread.
+            <p/>
+            Passing 0 as a sampling rate generates 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
+            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.
+        </error>
+      </errors>
+    </function>
+  </category>
 <errorsection label="Error Reference">
     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.

@@ -13493,11 +13542,78 @@
       <param id="object">
-            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"
+    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.  
+      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.
+      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.
+      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.
+      <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.
+      In conjunction with weak references and the function
+      <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
+      stack trace, and which are still live during the execution of the program.
+    </description>
+    <origin>new</origin>
+    <capabilities>
+      <required id="can_generate_sampled_object_alloc_events"></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.
       <param id="object_klass">
< prev index next >