--- a/src/hotspot/share/prims/jvmti.xml Mon Jun 11 15:28:24 2018 +0200
+++ b/src/hotspot/share/prims/jvmti.xml Fri Jun 15 00:49:54 2018 -0700
@@ -10353,6 +10353,14 @@
See <eventlink id="ClassFileLoadHook"/>.
</description>
</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
+ called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
+ </description>
+ </capabilityfield>
</capabilitiestypedef>
<function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
@@ -11531,6 +11539,47 @@
</category>
+ <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>
+
</functionsection>
<errorsection label="Error Reference">
@@ -13495,13 +13544,13 @@
<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
+ JNI local reference to the class of the object.
</description>
</param>
<param id="size">
@@ -13513,8 +13562,75 @@
</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.
+ </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="Object Free"
- id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
+ id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
<description>
An Object Free event is sent when the garbage collector frees an object.
Events are only sent for tagged objects--see
@@ -13534,7 +13650,7 @@
<jlong/>
<description>
The freed object's tag
- </description>
+ </description>
</param>
</parameters>
</event>