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