< prev index next >
src/hotspot/share/prims/jvmti.xml
Print this page
rev 48551 : [mq]: heap8
rev 48552 : [mq]: heap10a
rev 48556 : [mq]: heap17
rev 48559 : [mq]: heap20
*** 10351,10360 ****
--- 10351,10367 ----
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 methods can be called.
+ </description>
+ </capabilityfield>
</capabilitiestypedef>
<function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
<synopsis>Get Potential Capabilities</synopsis>
<description>
*** 11529,11538 ****
--- 11536,11840 ----
</errors>
</function>
</category>
+ <category id="heap_monitoring" label="Heap Monitoring">
+ <typedef id="jvmtiStackTrace" label="Stack Trace" since="11">
+ <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" since="11">
+ <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" since="11">
+ <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" since="11">
+ <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>,
+ or <functionlink id="GetCachedTraces"></functionlink> functions.
+ </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" since="11">
+ <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>,
+ or <functionlink id="GetCachedTraces"></functionlink> functions.
+
+ Stopping the heap sampler resets internal traces and counters. Therefore stopping the sampler frees any
+ internal trace samples, any subsequent call to the <functionlink id="GetLiveTraces"></functionlink>,
+ <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
+ or <functionlink id="GetCachedTraces"></functionlink> functions will return no traces.
+ </description>
+ <origin>new</origin>
+ <capabilities>
+ <required id="can_sample_heap"></required>
+ </capabilities>
+ <parameters>
+ </parameters>
+ <errors>
+ </errors>
+ </function>
+
+ <function id="GetLiveTraces" num="158" since="11">
+ <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 methods call full GC and can be costly. Use with care as it can affect performance. For
+ continuous profiling, perhaps prefer GetCachedTraces, which returns the live traces at the last
+ full GC point.
+
+ This method can be called at any time but if the sampler is not enabled, via
+ <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" since="11">
+ <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 is not enabled, via
+ <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" since="11">
+ <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 is not enabled, via
+ <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="GetCachedTraces" num="161" since="11">
+ <synopsis>Get Live Traces</synopsis>
+ <description>
+ Get the cached sampled traces: the traces are the ones that were collected during the last
+ full GC. 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 is not enabled, via
+ <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="162" since="11">
+ <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="163" since="11">
+ <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 >