< prev index next >
src/hotspot/share/prims/jvmti.xml
Print this page
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>
< prev index next >