10334 See <eventlink id="ResourceExhausted"/>.
10335 </description>
10336 </capabilityfield>
10337 <capabilityfield id="can_generate_early_vmstart" since="9">
10338 <description>
10339 Can generate the <code>VMStart</code> event early.
10340 See <eventlink id="VMStart"/>.
10341 </description>
10342 </capabilityfield>
10343 <capabilityfield id="can_generate_early_class_hook_events" since="9">
10344 <description>
10345 Can generate the <eventlink id="ClassFileLoadHook"/> events
10346 in the primordial phase. If this capability and
10347 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10348 <code>can_generate_all_class_hook_events</code></internallink>
10349 are enabled then the <eventlink id="ClassFileLoadHook"/> events
10350 can be posted for classes loaded in the primordial phase.
10351 See <eventlink id="ClassFileLoadHook"/>.
10352 </description>
10353 </capabilityfield>
10354 </capabilitiestypedef>
10355
10356 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10357 <synopsis>Get Potential Capabilities</synopsis>
10358 <description>
10359 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10360 features that can potentially be possessed by this environment
10361 at this time.
10362 The returned capabilities differ from the complete set of capabilities
10363 implemented by the VM in two cases: another environment possesses
10364 capabilities that can only be possessed by one environment, or the
10365 current <functionlink id="GetPhase">phase</functionlink> is live,
10366 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10367 The <functionlink id="AddCapabilities"></functionlink> function
10368 may be used to set any or all or these capabilities.
10369 Currently possessed capabilities are included.
10370 <p/>
10371 Typically this function is used in the <code>OnLoad</code> function.
10372 Some virtual machines may allow a limited set of capabilities to be
10373 added in the live phase.
11510 <constant id="JVMTI_JLOCATION_OTHER" num="0">
11511 <code>jlocation</code> values have some other representation.
11512 </constant>
11513 </constants>
11514 </description>
11515 <origin>new</origin>
11516 <capabilities>
11517 </capabilities>
11518 <parameters>
11519 <param id="format_ptr">
11520 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11521 <description>
11522 On return, points to the format identifier for <code>jlocation</code> values.
11523 </description>
11524 </param>
11525 </parameters>
11526 <errors>
11527 </errors>
11528 </function>
11529
11530 </category>
11531
11532 </functionsection>
11533
11534 <errorsection label="Error Reference">
11535 <intro>
11536 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11537 <p/>
11538 It is the responsibility of the agent to call <jvmti/> functions with
11539 valid parameters and in the proper context (calling thread is attached,
11540 phase is correct, etc.).
11541 Detecting some error conditions may be difficult, inefficient, or
11542 impossible for an implementation.
11543 The errors listed in
11544 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11545 must be detected by the implementation.
11546 All other errors represent the recommended response to the error
11547 condition.
11548 </intro>
11549
|
10334 See <eventlink id="ResourceExhausted"/>.
10335 </description>
10336 </capabilityfield>
10337 <capabilityfield id="can_generate_early_vmstart" since="9">
10338 <description>
10339 Can generate the <code>VMStart</code> event early.
10340 See <eventlink id="VMStart"/>.
10341 </description>
10342 </capabilityfield>
10343 <capabilityfield id="can_generate_early_class_hook_events" since="9">
10344 <description>
10345 Can generate the <eventlink id="ClassFileLoadHook"/> events
10346 in the primordial phase. If this capability and
10347 <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10348 <code>can_generate_all_class_hook_events</code></internallink>
10349 are enabled then the <eventlink id="ClassFileLoadHook"/> events
10350 can be posted for classes loaded in the primordial phase.
10351 See <eventlink id="ClassFileLoadHook"/>.
10352 </description>
10353 </capabilityfield>
10354
10355 <capabilityfield id="can_sample_heap" since="9">
10356 <description>
10357 Can sample the heap.
10358 If this capability is enabled then the heap sampling methods can be called.
10359 </description>
10360 </capabilityfield>
10361 </capabilitiestypedef>
10362
10363 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10364 <synopsis>Get Potential Capabilities</synopsis>
10365 <description>
10366 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10367 features that can potentially be possessed by this environment
10368 at this time.
10369 The returned capabilities differ from the complete set of capabilities
10370 implemented by the VM in two cases: another environment possesses
10371 capabilities that can only be possessed by one environment, or the
10372 current <functionlink id="GetPhase">phase</functionlink> is live,
10373 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10374 The <functionlink id="AddCapabilities"></functionlink> function
10375 may be used to set any or all or these capabilities.
10376 Currently possessed capabilities are included.
10377 <p/>
10378 Typically this function is used in the <code>OnLoad</code> function.
10379 Some virtual machines may allow a limited set of capabilities to be
10380 added in the live phase.
11517 <constant id="JVMTI_JLOCATION_OTHER" num="0">
11518 <code>jlocation</code> values have some other representation.
11519 </constant>
11520 </constants>
11521 </description>
11522 <origin>new</origin>
11523 <capabilities>
11524 </capabilities>
11525 <parameters>
11526 <param id="format_ptr">
11527 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11528 <description>
11529 On return, points to the format identifier for <code>jlocation</code> values.
11530 </description>
11531 </param>
11532 </parameters>
11533 <errors>
11534 </errors>
11535 </function>
11536
11537 </category>
11538
11539 <category id="heap_monitoring" label="Heap Monitoring">
11540 <typedef id="jvmtiStackTrace" label="Stack Trace">
11541 <field id="frames">
11542 <allocfieldbuf outcount="frame_count">
11543 <struct>jvmtiFrameInfo</struct>
11544 </allocfieldbuf>
11545 <description>Pointer to the call frames.</description>
11546 </field>
11547 <field id="frame_count">
11548 <jint/>
11549 <description>The number of frames for the trace.</description>
11550 </field>
11551 <field id="size">
11552 <jint/>
11553 <description>The size of the object allocation.</description>
11554 </field>
11555 <field id="thread_id">
11556 <jlong/>
11557 <description>The thread id number.</description>
11558 </field>
11559 </typedef>
11560
11561 <typedef id="jvmtiStackTraces" label="Stack Traces">
11562 <field id="stack_traces">
11563 <allocfieldbuf outcount="trace_count">
11564 <struct>jvmtiStackTrace</struct>
11565 </allocfieldbuf>
11566 <description>
11567 The <datalink id="jvmtiStackTrace"/> array with the various stack traces.
11568 </description>
11569 </field>
11570
11571 <field id="trace_count">
11572 <jint/>
11573 <description>
11574 Number of traces pointed by the array <datalink id="jvmtiStackTraces"/>.
11575 </description>
11576 </field>
11577 </typedef>
11578
11579 <typedef id="jvmtiHeapSamplingStats" label="Heap Sampling Statistics">
11580 <field id="sample_count">
11581 <jlong/>
11582 <description>
11583 The number of sampled allocations during the lifetime of the sampler.
11584 For very long sampling, this number can overflow.
11585 </description>
11586 </field>
11587
11588 <field id="garbage_collected_samples">
11589 <jlong/>
11590 <description>
11591 The number of samples already garbage collected.
11592 For very long sampling, this number can overflow.
11593 </description>
11594 </field>
11595
11596 <field id="sample_rate_accumulation">
11597 <jlong/>
11598 <description>
11599 Accumulation of the sample rates chosen.
11600 For very long sampling, this number can overflow.
11601 </description>
11602 </field>
11603
11604 <field id="sample_rate_count">
11605 <jlong/>
11606 <description>
11607 The number of sample rates chosen.
11608 For very long sampling, this number can overflow.
11609 </description>
11610 </field>
11611
11612 <field id="stack_depth_accumulation">
11613 <jlong/>
11614 <description>
11615 Accumulation of stack depths collected by the sampler.
11616 For very long sampling, this number can overflow.
11617 </description>
11618 </field>
11619 </typedef>
11620
11621 <function id="StartHeapSampling" phase="any" num="156">
11622 <synopsis>Start Heap Sampling</synopsis>
11623 <description>
11624 Start the heap sampler in the JVM. The function provides, via its argument, the sampling
11625 rate requested and will fill internal data structures with heap allocation samples. The
11626 samples are obtained via the <functionlink id="GetLiveTraces"></functionlink>,
11627 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11628 functions.
11629
11630 Starting the heap sampler resets internal traces and counters. Therefore stopping the sampler
11631 puts internal trace samples and counters on pause for post-processing.
11632 </description>
11633 <origin>new</origin>
11634 <capabilities>
11635 <required id="can_sample_heap"></required>
11636 </capabilities>
11637 <parameters>
11638 <param id="monitoring_rate">
11639 <jint/>
11640 <description>
11641 The monitoring rate used for sampling. The sampler will use a statistical approach to
11642 provide in average sampling every <paramlink id="monitoring_rate"/> allocated bytes.
11643
11644 Note: a low monitoring rate will incur a higher overhead, therefore, the sampler should
11645 only be used when knowing it may impact performance.
11646 </description>
11647 </param>
11648 <param id="max_gc_storage">
11649 <jint/>
11650 <description>
11651 The maximum storage used for the GC samples in the sampler. By default, the value is 200.
11652 </description>
11653 </param>
11654 </parameters>
11655 <errors>
11656 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11657 <paramlink id="monitoring_period"></paramlink> is less than zero.
11658 </error>
11659 </errors>
11660 </function>
11661
11662 <function id="StopHeapSampling" phase="any" num="157">
11663 <synopsis>Stop Heap Sampling</synopsis>
11664 <description>
11665 Stop the heap sampler in the JVM.
11666 Any sample obtained during sampling is still available via the <functionlink id="GetLiveTraces"></functionlink>,
11667 <functionlink id="GetGarbageTraces"></functionlink>, <functionlink id="GetFrequentGarbageTraces"></functionlink>,
11668 functions.
11669
11670 Starting the heap sampler resets internal traces and counters. Therefore stopping the sampler
11671 puts internal trace samples and counters on pause for post-processing.
11672 </description>
11673 <origin>new</origin>
11674 <capabilities>
11675 <required id="can_sample_heap"></required>
11676 </capabilities>
11677 <parameters>
11678 </parameters>
11679 <errors>
11680 </errors>
11681 </function>
11682
11683 <function id="GetLiveTraces" num="158">
11684 <synopsis>Get Live Traces</synopsis>
11685 <description>
11686 Get Live Heap Sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11687 structure are filled in with details of the specified sampled allocation.
11688
11689 This method can be called at any time but if the sampler has not been started via at least
11690 one call to <functionlink id="StartHeapSampling"></functionlink> it returns no traces.
11691 </description>
11692 <origin>new</origin>
11693 <capabilities>
11694 <required id="can_sample_heap"></required>
11695 </capabilities>
11696 <parameters>
11697 <param id="stack_traces">
11698 <outptr><struct>jvmtiStackTraces</struct></outptr>
11699 <description>
11700 The stack trace data structure to be filled.
11701 </description>
11702 </param>
11703 </parameters>
11704 <errors>
11705 </errors>
11706 </function>
11707
11708 <function id="GetGarbageTraces" num="159">
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 has not been started via at least
11715 one call to <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="stack_traces">
11723 <outptr><struct>jvmtiStackTraces</struct></outptr>
11724 <description>
11725 The stack trace data structure to be filled.
11726 </description>
11727 </param>
11728 </parameters>
11729 <errors>
11730 </errors>
11731 </function>
11732
11733 <function id="GetFrequentGarbageTraces" num="160">
11734 <synopsis>Get Frequent Garbage Traces</synopsis>
11735 <description>
11736 Get the frequent garbage heap sampled traces. The fields of the <datalink id="jvmtiStackTraces"/>
11737 structure are filled in with details of the specified sampled allocation.
11738
11739 This method can be called at any time but if the sampler has not been started via at least
11740 one call to <functionlink id="StartHeapSampling"></functionlink> it returns no traces.
11741 </description>
11742 <origin>new</origin>
11743 <capabilities>
11744 <required id="can_sample_heap"></required>
11745 </capabilities>
11746 <parameters>
11747 <param id="stack_traces">
11748 <outptr><struct>jvmtiStackTraces</struct></outptr>
11749 <description>
11750 The stack trace data structure to be filled.
11751 </description>
11752 </param>
11753 </parameters>
11754 <errors>
11755 </errors>
11756 </function>
11757
11758 <function id="ReleaseTraces" num="161">
11759 <synopsis>Release traces provided by the heap monitoring</synopsis>
11760 <description>
11761 Release traces provided by any of the trace retrieval methods.
11762 </description>
11763 <origin>new</origin>
11764 <capabilities>
11765 <required id="can_sample_heap"></required>
11766 </capabilities>
11767 <parameters>
11768 <param id="stack_traces">
11769 <outptr><struct>jvmtiStackTraces</struct></outptr>
11770 <description>
11771 The stack trace data structure to be released.
11772 </description>
11773 </param>
11774 </parameters>
11775 <errors>
11776 </errors>
11777 </function>
11778
11779 <function id="GetHeapSamplingStats" num="162">
11780 <synopsis>Get the heap sampling statistics</synopsis>
11781 <description>
11782 Returns a <datalink id="jvmtiHeapSamplingStats"/> to understand the heap sampling behavior and current
11783 internal data storage status.
11784
11785 This method can be called at any time but if the sampler has not been started via at least
11786 one call to <functionlink id="StartHeapSampling"></functionlink> it returns a zeroed-out structure.
11787 </description>
11788 <origin>new</origin>
11789 <capabilities>
11790 <required id="can_sample_heap"></required>
11791 </capabilities>
11792 <parameters>
11793 <param id="stats">
11794 <outptr><struct>jvmtiHeapSamplingStats</struct></outptr>
11795 <description>
11796 The structure to be filled with the heap sampler's statistics.
11797 </description>
11798 </param>
11799 </parameters>
11800 <errors>
11801 </errors>
11802 </function>
11803 </category>
11804
11805 </functionsection>
11806
11807 <errorsection label="Error Reference">
11808 <intro>
11809 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11810 <p/>
11811 It is the responsibility of the agent to call <jvmti/> functions with
11812 valid parameters and in the proper context (calling thread is attached,
11813 phase is correct, etc.).
11814 Detecting some error conditions may be difficult, inefficient, or
11815 impossible for an implementation.
11816 The errors listed in
11817 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11818 must be detected by the implementation.
11819 All other errors represent the recommended response to the error
11820 condition.
11821 </intro>
11822
|