10336 See <eventlink id="ResourceExhausted"/>.
10337 </description>
10338 </capabilityfield>
10339 <capabilityfield id="can_generate_early_vmstart" since="9">
10340 <description>
10341 Can generate the <code>VMStart</code> event early.
10342 See <eventlink id="VMStart"/>.
10343 </description>
10344 </capabilityfield>
10345 <capabilityfield id="can_generate_early_class_hook_events" since="9">
10346 <description>
10347 Can generate the <eventlink id="ClassFileLoadHook"/> events
10348 in the primordial phase. If this capability and
10349 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10350 <code>can_generate_all_class_hook_events</code></internallink>
10351 are enabled then the <eventlink id="ClassFileLoadHook"/> events
10352 can be posted for classes loaded in the primordial phase.
10353 See <eventlink id="ClassFileLoadHook"/>.
10354 </description>
10355 </capabilityfield>
10356 </capabilitiestypedef>
10357
10358 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10359 <synopsis>Get Potential Capabilities</synopsis>
10360 <description>
10361 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10362 features that can potentially be possessed by this environment
10363 at this time.
10364 The returned capabilities differ from the complete set of capabilities
10365 implemented by the VM in two cases: another environment possesses
10366 capabilities that can only be possessed by one environment, or the
10367 current <functionlink id="GetPhase">phase</functionlink> is live,
10368 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10369 The <functionlink id="AddCapabilities"></functionlink> function
10370 may be used to set any or all or these capabilities.
10371 Currently possessed capabilities are included.
10372 <p/>
10373 Typically this function is used in the <code>OnLoad</code> function.
10374 Some virtual machines may allow a limited set of capabilities to be
10375 added in the live phase.
11512 <constant id="JVMTI_JLOCATION_OTHER" num="0">
11513 <code>jlocation</code> values have some other representation.
11514 </constant>
11515 </constants>
11516 </description>
11517 <origin>new</origin>
11518 <capabilities>
11519 </capabilities>
11520 <parameters>
11521 <param id="format_ptr">
11522 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11523 <description>
11524 On return, points to the format identifier for <code>jlocation</code> values.
11525 </description>
11526 </param>
11527 </parameters>
11528 <errors>
11529 </errors>
11530 </function>
11531
11532 </category>
11533
11534 </functionsection>
11535
11536 <errorsection label="Error Reference">
11537 <intro>
11538 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11539 <p/>
11540 It is the responsibility of the agent to call <jvmti/> functions with
11541 valid parameters and in the proper context (calling thread is attached,
11542 phase is correct, etc.).
11543 Detecting some error conditions may be difficult, inefficient, or
11544 impossible for an implementation.
11545 The errors listed in
11546 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11547 must be detected by the implementation.
11548 All other errors represent the recommended response to the error
11549 condition.
11550 </intro>
11551
|
10336 See <eventlink id="ResourceExhausted"/>.
10337 </description>
10338 </capabilityfield>
10339 <capabilityfield id="can_generate_early_vmstart" since="9">
10340 <description>
10341 Can generate the <code>VMStart</code> event early.
10342 See <eventlink id="VMStart"/>.
10343 </description>
10344 </capabilityfield>
10345 <capabilityfield id="can_generate_early_class_hook_events" since="9">
10346 <description>
10347 Can generate the <eventlink id="ClassFileLoadHook"/> events
10348 in the primordial phase. If this capability and
10349 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10350 <code>can_generate_all_class_hook_events</code></internallink>
10351 are enabled then the <eventlink id="ClassFileLoadHook"/> events
10352 can be posted for classes loaded in the primordial phase.
10353 See <eventlink id="ClassFileLoadHook"/>.
10354 </description>
10355 </capabilityfield>
10356
10357 <capabilityfield id="can_sample_heap" since="11">
10358 <description>
10359 Can sample the heap.
10360 If this capability is enabled then the heap sampling methods can be called.
10361 </description>
10362 </capabilityfield>
10363 </capabilitiestypedef>
10364
10365 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10366 <synopsis>Get Potential Capabilities</synopsis>
10367 <description>
10368 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10369 features that can potentially be possessed by this environment
10370 at this time.
10371 The returned capabilities differ from the complete set of capabilities
10372 implemented by the VM in two cases: another environment possesses
10373 capabilities that can only be possessed by one environment, or the
10374 current <functionlink id="GetPhase">phase</functionlink> is live,
10375 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10376 The <functionlink id="AddCapabilities"></functionlink> function
10377 may be used to set any or all or these capabilities.
10378 Currently possessed capabilities are included.
10379 <p/>
10380 Typically this function is used in the <code>OnLoad</code> function.
10381 Some virtual machines may allow a limited set of capabilities to be
10382 added in the live phase.
11519 <constant id="JVMTI_JLOCATION_OTHER" num="0">
11520 <code>jlocation</code> values have some other representation.
11521 </constant>
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
11576 <field id="sample_rate_accumulation">
11577 <jlong/>
11578 <description>
11579 Accumulation of the sample rates chosen.
11580 For very long sampling, this number can overflow.
11581 </description>
11582 </field>
11583
11584 <field id="sample_rate_count">
11585 <jlong/>
11586 <description>
11587 The number of sample rates chosen.
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>
11856 <errors>
11857 </errors>
11858 </function>
11859 </category>
11860
11861 </functionsection>
11862
11863 <errorsection label="Error Reference">
11864 <intro>
11865 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11866 <p/>
11867 It is the responsibility of the agent to call <jvmti/> functions with
11868 valid parameters and in the proper context (calling thread is attached,
11869 phase is correct, etc.).
11870 Detecting some error conditions may be difficult, inefficient, or
11871 impossible for an implementation.
11872 The errors listed in
11873 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11874 must be detected by the implementation.
11875 All other errors represent the recommended response to the error
11876 condition.
11877 </intro>
11878
|