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="9">
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="jvmtiStackTrace" label="Stack Trace">
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">
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">
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
11598 <field id="sample_rate_accumulation">
11599 <jlong/>
11600 <description>
11601 Accumulation of the sample rates chosen.
11602 For very long sampling, this number can overflow.
11603 </description>
11604 </field>
11605
11606 <field id="sample_rate_count">
11607 <jlong/>
11608 <description>
11609 The number of sample rates chosen.
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">
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">
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">
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">
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">
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">
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">
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">
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>
11831 <errors>
11832 </errors>
11833 </function>
11834 </category>
11835
11836 </functionsection>
11837
11838 <errorsection label="Error Reference">
11839 <intro>
11840 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11841 <p/>
11842 It is the responsibility of the agent to call <jvmti/> functions with
11843 valid parameters and in the proper context (calling thread is attached,
11844 phase is correct, etc.).
11845 Detecting some error conditions may be difficult, inefficient, or
11846 impossible for an implementation.
11847 The errors listed in
11848 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11849 must be detected by the implementation.
11850 All other errors represent the recommended response to the error
11851 condition.
11852 </intro>
11853
|