< prev index next >
src/hotspot/share/prims/jvmti.xml
Print this page
rev 49264 : [mq]: event-only
rev 49265 : [mq]: event3
rev 49266 : [mq]: event4
rev 49267 : [mq]: event5
rev 49268 : [mq]: event6
rev 49269 : [mq]: event7
@@ -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_generate_sampled_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 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,51 @@
</errors>
</function>
</category>
+ <category id="heap_monitoring" label="Heap Monitoring">
+ <function id="SetHeapSamplingRate" phase="onload" num="156" since="11">
+ <synopsis>Set Heap Sampling Rate</synopsis>
+ <description>
+ 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.
+ <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_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>
+ </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 +13542,74 @@
</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"
+ id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11">
+ <description>
+ Sent when an allocated object is sampled via the
+ <internallink id="heap_monitoring"> Heap Sampling Monitoring system </internallink>.
+ <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 sampled 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_generate_sampled_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>
< prev index next >