< prev index next >
src/hotspot/share/prims/jvmti.xml
Print this page
rev 47590 : [mq]: heap8
rev 47591 : [mq]: heap10a
@@ -10349,10 +10349,17 @@
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="9">
+ <description>
+ Can sample the heap.
+ If this capability is enabled then the heap sampling methods can be called.
+ </description>
+ </capabilityfield>
</capabilitiestypedef>
<function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
<synopsis>Get Potential Capabilities</synopsis>
<description>
@@ -11527,10 +11534,276 @@
</errors>
</function>
</category>
+ <category id="heap_monitoring" label="Heap Monitoring">
+ <typedef id="jvmtiStackTrace" label="Stack Trace">
+ <field id="frames">
+ <allocfieldbuf outcount="frame_count">
+ <struct>jvmtiFrameInfo</struct>
+ </allocfieldbuf>
+ <description>Pointer to the call frames.</description>
+ </field>
+ <field id="frame_count">
+ <jint/>
+ <description>The number of frames for the trace.</description>
+ </field>
+ <field id="size">
+ <jint/>
+ <description>The size of the object allocation.</description>
+ </field>
+ <field id="thread_id">
+ <jlong/>
+ <description>The thread id number.</description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiStackTraces" label="Stack Traces">
+ <field id="stack_traces">
+ <allocfieldbuf outcount="trace_count">
+ <struct>jvmtiStackTrace</struct>
+ </allocfieldbuf>
+ <description>
+ The <datalink id="jvmtiStackTrace"/> array with the various stack traces.
+ </description>
+ </field>
+
+ <field id="trace_count">
+ <jint/>
+ <description>
+ Number of traces pointed by the array <datalink id="jvmtiStackTraces"/>.
+ </description>
+ </field>
+ </typedef>
+
+ <typedef id="jvmtiHeapSamplingStats" label="Heap Sampling Statistics">
+ <field id="sample_count">
+ <jlong/>
+ <description>
+ The number of sampled allocations during the lifetime of the sampler.
+ For very long sampling, this number can overflow.
+ </description>
+ </field>
+
+ <field id="garbage_collected_samples">
+ <jlong/>
+ <description>
+ The number of samples already garbage collected.
+ For very long sampling, this number can overflow.
+ </description>
+ </field>
+
+ <field id="sample_rate_accumulation">
+ <jlong/>
+ <description>
+ Accumulation of the sample rates chosen.
+ For very long sampling, this number can overflow.
+ </description>
+ </field>
+
+ <field id="sample_rate_count">
+ <jlong/>
+ <description>
+ The number of sample rates chosen.
+ For very long sampling, this number can overflow.
+ </description>
+ </field>
+
+ <field id="stack_depth_accumulation">
+ <jlong/>
+ <description>
+ Accumulation of stack depths collected by the sampler.
+ For very long sampling, this number can overflow.
+ </description>
+ </field>
+ </typedef>
+
+ <function id="StartHeapSampling" phase="any" num="156">
+ <synopsis>Start Heap Sampling</synopsis>
+ <description>
+ Start the heap sampler in the JVM. The function provides, via its argument, the sampling
+ rate requested and will fill internal data structures with heap allocation samples. The
+ samples are obtained via the <functionlink id="GetLiveTraces"></functionlink>,
+ <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
+ functions.
+
+ Starting the heap sampler resets internal traces and counters. Therefore stopping the sampler
+ puts internal trace samples and counters on pause for post-processing.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ <param id="monitoring_rate">
+ <jint/>
+ <description>
+ The monitoring rate used for sampling. The sampler will use a statistical approach to
+ provide in average sampling every <paramlink id="monitoring_rate"/> allocated bytes.
+
+ Note: a low monitoring rate will incur a higher overhead, therefore, the sampler should
+ only be used when knowing it may impact performance.
+ </description>
+ </param>
+ <param id="max_gc_storage">
+ <jint/>
+ <description>
+ The maximum storage used for the GC samples in the sampler. By default, the value is 200.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
+ <paramlink id="monitoring_period"></paramlink> is less than zero.
+ </error>
+ </errors>
+ </function>
+
+ <function id="StopHeapSampling" phase="any" num="157">
+ <synopsis>Stop Heap Sampling</synopsis>
+ <description>
+ Stop the heap sampler in the JVM.
+ Any sample obtained during sampling is still available via the <functionlink id="GetLiveTraces"></functionlink>,
+ <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
+ functions.
+
+ Starting the heap sampler resets internal traces and counters. Therefore stopping the sampler
+ puts internal trace samples and counters on pause for post-processing.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetLiveTraces" num="158">
+ <synopsis>Get Live Traces</synopsis>
+ <description>
+ Get Live Heap Sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
+ structure are filled in with details of the specified sampled allocation.
+
+ This method can be called at any time but if the sampler has not been started via at least
+ one call to <functionlink id="StartHeapSampling"></functionlink> it returns no traces.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ <param id="stack_traces">
+ <outptr><struct>jvmtiStackTraces</struct></outptr>
+ <description>
+ The stack trace data structure to be filled.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetGarbageTraces" num="159">
+ <synopsis>Get Garbage Traces</synopsis>
+ <description>
+ Get the recent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
+ structure are filled in with details of the specified sampled allocation.
+
+ This method can be called at any time but if the sampler has not been started via at least
+ one call to <functionlink id="StartHeapSampling"></functionlink> it returns no traces.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ <param id="stack_traces">
+ <outptr><struct>jvmtiStackTraces</struct></outptr>
+ <description>
+ The stack trace data structure to be filled.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetFrequentGarbageTraces" num="160">
+ <synopsis>Get Frequent Garbage Traces</synopsis>
+ <description>
+ Get the frequent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
+ structure are filled in with details of the specified sampled allocation.
+
+ This method can be called at any time but if the sampler has not been started via at least
+ one call to <functionlink id="StartHeapSampling"></functionlink> it returns no traces.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ <param id="stack_traces">
+ <outptr><struct>jvmtiStackTraces</struct></outptr>
+ <description>
+ The stack trace data structure to be filled.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="ReleaseTraces" num="161">
+ <synopsis>Release traces provided by the heap monitoring</synopsis>
+ <description>
+ Release traces provided by any of the trace retrieval methods.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ <param id="stack_traces">
+ <outptr><struct>jvmtiStackTraces</struct></outptr>
+ <description>
+ The stack trace data structure to be released.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetHeapSamplingStats" num="162">
+ <synopsis>Get the heap sampling statistics</synopsis>
+ <description>
+ Returns a <datalink id="jvmtiHeapSamplingStats"/> to understand the heap sampling behavior and current
+ internal data storage status.
+
+ This method can be called at any time but if the sampler has not been started via at least
+ one call to <functionlink id="StartHeapSampling"></functionlink> it returns a zeroed-out structure.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ <param id="stats">
+ <outptr><struct>jvmtiHeapSamplingStats</struct></outptr>
+ <description>
+ The structure to be filled with the heap sampler's statistics.
+ </description>
+ </param>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+ </category>
+
</functionsection>
<errorsection label="Error Reference">
<intro>
Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
< prev index next >