11522 </constants>
11523 </description>
11524 <origin>new</origin>
11525 <capabilities>
11526 </capabilities>
11527 <parameters>
11528 <param id="format_ptr">
11529 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11530 <description>
11531 On return, points to the format identifier for <code>jlocation</code> values.
11532 </description>
11533 </param>
11534 </parameters>
11535 <errors>
11536 </errors>
11537 </function>
11538
11539 </category>
11540
11541 <category id="heap_monitoring" label="Heap Monitoring">
11542 <typedef id="jvmtiStackTrace" label="Stack Trace" since="11">
11543 <field id="frames">
11544 <allocfieldbuf outcount="frame_count">
11545 <struct>jvmtiFrameInfo</struct>
11546 </allocfieldbuf>
11547 <description>Pointer to the call frames.</description>
11548 </field>
11549 <field id="frame_count">
11550 <jint/>
11551 <description>The number of frames for the trace.</description>
11552 </field>
11553 <field id="size">
11554 <jint/>
11555 <description>The size of the object allocation.</description>
11556 </field>
11557 <field id="thread_id">
11558 <jlong/>
11559 <description>The thread id number.</description>
11560 </field>
11561 </typedef>
11562
11563 <typedef id="jvmtiStackTraces" label="Stack Traces" since="11">
11564 <field id="stack_traces">
11565 <allocfieldbuf outcount="trace_count">
11566 <struct>jvmtiStackTrace</struct>
11567 </allocfieldbuf>
11568 <description>
11569 The <datalink id="jvmtiStackTrace"/> array with the various stack traces.
11570 </description>
11571 </field>
11572
11573 <field id="trace_count">
11574 <jint/>
11575 <description>
11576 Number of traces pointed by the array <datalink id="jvmtiStackTraces"/>.
11577 </description>
11578 </field>
11579 </typedef>
11580
11581 <typedef id="jvmtiHeapSamplingStats" label="Heap Sampling Statistics" since="11">
11582 <field id="sample_count">
11583 <jlong/>
11584 <description>
11585 The number of sampled allocations during the lifetime of the sampler.
11586 For very long sampling, this number can overflow.
11587 </description>
11588 </field>
11589
11590 <field id="garbage_collected_samples">
11591 <jlong/>
11592 <description>
11593 The number of samples already garbage collected.
11594 For very long sampling, this number can overflow.
11595 </description>
11596 </field>
11597
11610 For very long sampling, this number can overflow.
11611 </description>
11612 </field>
11613
11614 <field id="stack_depth_accumulation">
11615 <jlong/>
11616 <description>
11617 Accumulation of stack depths collected by the sampler.
11618 For very long sampling, this number can overflow.
11619 </description>
11620 </field>
11621 </typedef>
11622
11623 <function id="StartHeapSampling" phase="any" num="156" since="11">
11624 <synopsis>Start Heap Sampling</synopsis>
11625 <description>
11626 Start the heap sampler in the JVM. The function provides, via its argument, the sampling
11627 rate requested and will fill internal data structures with heap allocation samples. The
11628 samples are obtained via the <functionlink id="GetLiveTraces"></functionlink>,
11629 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11630 or <functionlink id="GetCachedTraces"></functionlink> functions.
11631 </description>
11632 <origin>new</origin>
11633 <capabilities>
11634 <required id="can_sample_heap"></required>
11635 </capabilities>
11636 <parameters>
11637 <param id="monitoring_rate">
11638 <jint/>
11639 <description>
11640 The monitoring rate used for sampling. The sampler will use a statistical approach to
11641 provide in average sampling every <paramlink id="monitoring_rate"/> allocated bytes.
11642
11643 Note: a low monitoring rate will incur a higher overhead, therefore, the sampler should
11644 only be used when knowing it may impact performance.
11645 </description>
11646 </param>
11647 <param id="max_gc_storage">
11648 <jint/>
11649 <description>
11650 The maximum storage used for the GC samples in the sampler. By default, the value is 200.
11651 </description>
11652 </param>
11653 </parameters>
11654 <errors>
11655 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11656 <paramlink id="monitoring_period"></paramlink> is less than zero.
11657 </error>
11658 </errors>
11659 </function>
11660
11661 <function id="StopHeapSampling" phase="any" num="157" since="11">
11662 <synopsis>Stop Heap Sampling</synopsis>
11663 <description>
11664 Stop the heap sampler in the JVM.
11665 Any sample obtained during sampling is still available via the <functionlink id="GetLiveTraces"></functionlink>,
11666 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11667 or <functionlink id="GetCachedTraces"></functionlink> functions.
11668
11669 Stopping the heap sampler resets internal traces and counters. Therefore stopping the sampler frees any
11670 internal trace samples, any subsequent call to the <functionlink id="GetLiveTraces"></functionlink>,
11671 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11672 or <functionlink id="GetCachedTraces"></functionlink> functions will return no traces.
11673 </description>
11674 <origin>new</origin>
11675 <capabilities>
11676 <required id="can_sample_heap"></required>
11677 </capabilities>
11678 <parameters>
11679 </parameters>
11680 <errors>
11681 </errors>
11682 </function>
11683
11684 <function id="GetLiveTraces" num="158" since="11">
11685 <synopsis>Get Live Traces</synopsis>
11686 <description>
11687 Get Live Heap Sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11688 structure are filled in with details of the specified sampled allocation.
11689
11690 This methods call full GC and can be costly. Use with care as it can affect performance. For
11691 continuous profiling, perhaps prefer GetCachedTraces, which returns the live traces at the last
11692 full GC point.
11693
11694 This method can be called at any time but if the sampler is not enabled, via
11695 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11696 </description>
11697 <origin>new</origin>
11698 <capabilities>
11699 <required id="can_sample_heap"></required>
11700 </capabilities>
11701 <parameters>
11702 <param id="stack_traces">
11703 <outptr><struct>jvmtiStackTraces</struct></outptr>
11704 <description>
11705 The stack trace data structure to be filled.
11706 </description>
11707 </param>
11708 </parameters>
11709 <errors>
11710 </errors>
11711 </function>
11712
11713 <function id="GetGarbageTraces" num="159" since="11">
11714 <synopsis>Get Garbage Traces</synopsis>
11715 <description>
11716 Get the recent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11717 structure are filled in with details of the specified sampled allocation.
11718
11719 This method can be called at any time but if the sampler is not enabled, via
11720 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11721 </description>
11722 <origin>new</origin>
11723 <capabilities>
11724 <required id="can_sample_heap"></required>
11725 </capabilities>
11726 <parameters>
11727 <param id="stack_traces">
11728 <outptr><struct>jvmtiStackTraces</struct></outptr>
11729 <description>
11730 The stack trace data structure to be filled.
11731 </description>
11732 </param>
11733 </parameters>
11734 <errors>
11735 </errors>
11736 </function>
11737
11738 <function id="GetFrequentGarbageTraces" num="160" since="11">
11739 <synopsis>Get Frequent Garbage Traces</synopsis>
11740 <description>
11741 Get the frequent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11742 structure are filled in with details of the specified sampled allocation.
11743
11744 This method can be called at any time but if the sampler is not enabled, via
11745 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11746 </description>
11747 <origin>new</origin>
11748 <capabilities>
11749 <required id="can_sample_heap"></required>
11750 </capabilities>
11751 <parameters>
11752 <param id="stack_traces">
11753 <outptr><struct>jvmtiStackTraces</struct></outptr>
11754 <description>
11755 The stack trace data structure to be filled.
11756 </description>
11757 </param>
11758 </parameters>
11759 <errors>
11760 </errors>
11761 </function>
11762
11763 <function id="GetCachedTraces" num="161" since="11">
11764 <synopsis>Get Live Traces</synopsis>
11765 <description>
11766 Get the cached sampled traces: the traces are the ones that were collected during the last
11767 full GC. The fields of the <datalink id="jvmtiStackTraces"/> structure are filled in with
11768 details of the specified sampled allocation.
11769
11770 This method can be called at any time but if the sampler is not enabled, via
11771 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11772 </description>
11773 <origin>new</origin>
11774 <capabilities>
11775 <required id="can_sample_heap"></required>
11776 </capabilities>
11777 <parameters>
11778 <param id="stack_traces">
11779 <outptr><struct>jvmtiStackTraces</struct></outptr>
11780 <description>
11781 The stack trace data structure to be filled.
11782 </description>
11783 </param>
11784 </parameters>
11785 <errors>
11786 </errors>
11787 </function>
11788
11789 <function id="ReleaseTraces" num="162" since="11">
11790 <synopsis>Release traces provided by the heap monitoring</synopsis>
11791 <description>
11792 Release traces provided by any of the trace retrieval methods.
11793 </description>
11794 <origin>new</origin>
11795 <capabilities>
11796 <required id="can_sample_heap"></required>
11797 </capabilities>
11798 <parameters>
11799 <param id="stack_traces">
11800 <outptr><struct>jvmtiStackTraces</struct></outptr>
11801 <description>
11802 The stack trace data structure to be released.
11803 </description>
11804 </param>
11805 </parameters>
11806 <errors>
11807 </errors>
11808 </function>
11809
11810 <function id="GetHeapSamplingStats" num="163" since="11">
11811 <synopsis>Get the heap sampling statistics</synopsis>
11812 <description>
11813 Returns a <datalink id="jvmtiHeapSamplingStats"/> to understand the heap sampling behavior and current
11814 internal data storage status.
11815
11816 This method can be called at any time but if the sampler has not been started via at least
11817 one call to <functionlink id="StartHeapSampling"></functionlink> it returns a zeroed-out structure.
11818 </description>
11819 <origin>new</origin>
11820 <capabilities>
11821 <required id="can_sample_heap"></required>
11822 </capabilities>
11823 <parameters>
11824 <param id="stats">
11825 <outptr><struct>jvmtiHeapSamplingStats</struct></outptr>
11826 <description>
11827 The structure to be filled with the heap sampler's statistics.
11828 </description>
11829 </param>
11830 </parameters>
|
11522 </constants>
11523 </description>
11524 <origin>new</origin>
11525 <capabilities>
11526 </capabilities>
11527 <parameters>
11528 <param id="format_ptr">
11529 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11530 <description>
11531 On return, points to the format identifier for <code>jlocation</code> values.
11532 </description>
11533 </param>
11534 </parameters>
11535 <errors>
11536 </errors>
11537 </function>
11538
11539 </category>
11540
11541 <category id="heap_monitoring" label="Heap Monitoring">
11542 <typedef id="jvmtiAllocTraceInfo" label="Allocation Trace Information" since="11">
11543 <field id="stack_info">
11544 <allocfieldbuf>
11545 <struct>jvmtiStackInfo</struct>
11546 </allocfieldbuf>
11547 <description>Pointer to the stack information.</description>
11548 </field>
11549 <field id="size">
11550 <jlong/>
11551 <description>The size of the object allocation.</description>
11552 </field>
11553 <field id="thread_id">
11554 <jint/>
11555 <description>The thread id of the object allocation.</description>
11556 </field>
11557 </typedef>
11558
11559 <typedef id="jvmtiHeapSamplingStats" label="Heap Sampling Statistics" since="11">
11560 <field id="sample_count">
11561 <jlong/>
11562 <description>
11563 The number of sampled allocations during the lifetime of the sampler.
11564 For very long sampling, this number can overflow.
11565 </description>
11566 </field>
11567
11568 <field id="garbage_collected_samples">
11569 <jlong/>
11570 <description>
11571 The number of samples already garbage collected.
11572 For very long sampling, this number can overflow.
11573 </description>
11574 </field>
11575
11588 For very long sampling, this number can overflow.
11589 </description>
11590 </field>
11591
11592 <field id="stack_depth_accumulation">
11593 <jlong/>
11594 <description>
11595 Accumulation of stack depths collected by the sampler.
11596 For very long sampling, this number can overflow.
11597 </description>
11598 </field>
11599 </typedef>
11600
11601 <function id="StartHeapSampling" phase="any" num="156" since="11">
11602 <synopsis>Start Heap Sampling</synopsis>
11603 <description>
11604 Start the heap sampler in the JVM. The function provides, via its argument, the sampling
11605 rate requested and will fill internal data structures with heap allocation samples. The
11606 samples are obtained via the <functionlink id="GetLiveTraces"></functionlink>,
11607 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11608 or <functionlink id="GetCachedObjectAllocTraces"></functionlink> functions.
11609 </description>
11610 <origin>new</origin>
11611 <capabilities>
11612 <required id="can_sample_heap"></required>
11613 </capabilities>
11614 <parameters>
11615 <param id="monitoring_rate">
11616 <jint/>
11617 <description>
11618 The monitoring rate used for sampling. The sampler will use a statistical approach to
11619 provide in average sampling every <paramlink id="monitoring_rate"/> allocated bytes.
11620
11621 Note: a low monitoring rate will incur a higher overhead, therefore, the sampler should
11622 only be used when knowing it may impact performance.
11623 </description>
11624 </param>
11625 <param id="max_gc_storage">
11626 <jint/>
11627 <description>
11628 The maximum storage used for the GC samples in the sampler. By default, the value is 200.
11629 </description>
11630 </param>
11631 </parameters>
11632 <errors>
11633 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11634 <paramlink id="monitoring_period"></paramlink> is less than zero.
11635 </error>
11636 </errors>
11637 </function>
11638
11639 <function id="StopHeapSampling" phase="any" num="157" since="11">
11640 <synopsis>Stop Heap Sampling</synopsis>
11641 <description>
11642 Stop the heap sampler in the JVM.
11643 Any sample obtained during sampling is still available via the <functionlink id="GetLiveTraces"></functionlink>,
11644 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11645 or <functionlink id="GetCachedObjectAllocTraces"></functionlink> functions.
11646
11647 Stopping the heap sampler resets internal traces and counters. Therefore stopping the sampler frees any
11648 internal trace samples, any subsequent call to the <functionlink id="GetLiveTraces"></functionlink>,
11649 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11650 or <functionlink id="GetCachedObjectAllocTraces"></functionlink> functions will return no traces.
11651 </description>
11652 <origin>new</origin>
11653 <capabilities>
11654 <required id="can_sample_heap"></required>
11655 </capabilities>
11656 <parameters>
11657 </parameters>
11658 <errors>
11659 </errors>
11660 </function>
11661
11662 <function id="GetObjectAllocTraces" num="158" since="11">
11663 <synopsis>Get Object Allocation Traces</synopsis>
11664 <description>
11665 Get Live Heap Sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11666 structure are filled in with details of the specified sampled allocation.
11667
11668 This methods call full GC and can be costly. Use with care as it can affect performance. For
11669 continuous profiling, perhaps prefer GetCachedObjectAllocTraces, which returns the live
11670 traces at the last full GC point.
11671
11672 This method can be called at any time but if the sampler is not enabled, via
11673 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11674 </description>
11675 <origin>new</origin>
11676 <capabilities>
11677 <required id="can_sample_heap"></required>
11678 </capabilities>
11679 <parameters>
11680 <param id="trace_info_ptr">
11681 <allocbuf>
11682 <struct>jvmtiAllocTraceInfo</struct>
11683 </allocbuf>
11684 <description>
11685 On return, this buffer is filled with stack information for each live object.
11686 The number of <datalink id="jvmtiAllocTraceInfo"/> records is determined
11687 by <paramlink id="trace_count_ptr"/>.
11688 <p/>
11689 Note that this buffer is allocated to include the <datalink id="jvmtiStackInfo"/>
11690 buffers pointed to by <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>, which also
11691 include the <datalink id="jvmtiFrameInfo"/> buffers pointed by
11692 <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>.
11693
11694 All these buffers must not be separately deallocated.
11695 </description>
11696 </param>
11697 <param id="trace_count_ptr">
11698 <outptr><jint/></outptr>
11699 <description>
11700 The number of traces allocated.
11701 </description>
11702 </param>
11703 </parameters>
11704 <errors>
11705 </errors>
11706 </function>
11707
11708 <function id="GetGarbageTraces" num="159" since="11">
11709 <synopsis>Get Garbage Traces</synopsis>
11710 <description>
11711 Get the recent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11712 structure are filled in with details of the specified sampled allocation.
11713
11714 This method can be called at any time but if the sampler is not enabled, via
11715 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11716 </description>
11717 <origin>new</origin>
11718 <capabilities>
11719 <required id="can_sample_heap"></required>
11720 </capabilities>
11721 <parameters>
11722 <param id="trace_info_ptr">
11723 <allocbuf>
11724 <struct>jvmtiAllocTraceInfo</struct>
11725 </allocbuf>
11726 <description>
11727 On return, this buffer is filled with stack information for each live object.
11728 The number of <datalink id="jvmtiAllocTraceInfo"/> records is determined
11729 by <paramlink id="trace_count_ptr"/>.
11730 <p/>
11731 Note that this buffer is allocated to include the <datalink id="jvmtiStackInfo"/>
11732 buffers pointed to by <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>, which also
11733 include the <datalink id="jvmtiFrameInfo"/> buffers pointed by
11734 <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>.
11735
11736 All these buffers must not be separately deallocated.
11737 </description>
11738 </param>
11739 <param id="trace_count_ptr">
11740 <outptr><jint/></outptr>
11741 <description>
11742 The number of traces allocated.
11743 </description>
11744 </param>
11745 </parameters>
11746 <errors>
11747 </errors>
11748 </function>
11749
11750 <function id="GetFrequentGarbageTraces" num="160" since="11">
11751 <synopsis>Get Frequent Garbage Traces</synopsis>
11752 <description>
11753 Get the frequent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11754 structure are filled in with details of the specified sampled allocation.
11755
11756 This method can be called at any time but if the sampler is not enabled, via
11757 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11758 </description>
11759 <origin>new</origin>
11760 <capabilities>
11761 <required id="can_sample_heap"></required>
11762 </capabilities>
11763 <parameters>
11764 <param id="trace_info_ptr">
11765 <allocbuf>
11766 <struct>jvmtiAllocTraceInfo</struct>
11767 </allocbuf>
11768 <description>
11769 On return, this buffer is filled with stack information for each live object.
11770 The number of <datalink id="jvmtiAllocTraceInfo"/> records is determined
11771 by <paramlink id="trace_count_ptr"/>.
11772 <p/>
11773 Note that this buffer is allocated to include the <datalink id="jvmtiStackInfo"/>
11774 buffers pointed to by <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>, which also
11775 include the <datalink id="jvmtiFrameInfo"/> buffers pointed by
11776 <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>.
11777
11778 All these buffers must not be separately deallocated.
11779 </description>
11780 </param>
11781 <param id="trace_count_ptr">
11782 <outptr><jint/></outptr>
11783 <description>
11784 The number of traces allocated.
11785 </description>
11786 </param>
11787 </parameters>
11788 <errors>
11789 </errors>
11790 </function>
11791
11792 <function id="GetCachedObjectAllocTraces" num="161" since="11">
11793 <synopsis>Get Cached Object Allocated Traces</synopsis>
11794 <description>
11795 Get the cached sampled traces: the traces are the ones that were collected during the last
11796 full GC. The fields of the <datalink id="jvmtiStackTraces"/> structure are filled in with
11797 details of the specified sampled allocation.
11798
11799 This method can be called at any time but if the sampler is not enabled, via
11800 <functionlink id="StartHeapSampling"></functionlink>, it returns no traces.
11801 </description>
11802 <origin>new</origin>
11803 <capabilities>
11804 <required id="can_sample_heap"></required>
11805 </capabilities>
11806 <parameters>
11807 <param id="trace_info_ptr">
11808 <allocbuf>
11809 <struct>jvmtiAllocTraceInfo</struct>
11810 </allocbuf>
11811 <description>
11812 On return, this buffer is filled with stack information for each live object.
11813 The number of <datalink id="jvmtiAllocTraceInfo"/> records is determined
11814 by <paramlink id="trace_count_ptr"/>.
11815 <p/>
11816 Note that this buffer is allocated to include the <datalink id="jvmtiStackInfo"/>
11817 buffers pointed to by <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>, which also
11818 include the <datalink id="jvmtiFrameInfo"/> buffers pointed by
11819 <datalink id="jvmtiAllocTraceInfo.frame_buffer"/>.
11820
11821 All these buffers must not be separately deallocated.
11822 </description>
11823 </param>
11824 <param id="trace_count_ptr">
11825 <outptr><jint/></outptr>
11826 <description>
11827 The number of traces allocated.
11828 </description>
11829 </param>
11830 </parameters>
11831 <errors>
11832 </errors>
11833 </function>
11834
11835 <function id="GetHeapSamplingStats" num="162" since="11">
11836 <synopsis>Get the heap sampling statistics</synopsis>
11837 <description>
11838 Returns a <datalink id="jvmtiHeapSamplingStats"/> to understand the heap sampling behavior and current
11839 internal data storage status.
11840
11841 This method can be called at any time but if the sampler has not been started via at least
11842 one call to <functionlink id="StartHeapSampling"></functionlink> it returns a zeroed-out structure.
11843 </description>
11844 <origin>new</origin>
11845 <capabilities>
11846 <required id="can_sample_heap"></required>
11847 </capabilities>
11848 <parameters>
11849 <param id="stats">
11850 <outptr><struct>jvmtiHeapSamplingStats</struct></outptr>
11851 <description>
11852 The structure to be filled with the heap sampler's statistics.
11853 </description>
11854 </param>
11855 </parameters>
|