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.
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
11552 <errorcategory id="universal-error" label="Universal Errors">
11553 <intro>
13478 <required id="can_generate_vm_object_alloc_events"></required>
13479 </capabilities>
13480 <parameters>
13481 <param id="jni_env">
13482 <outptr>
13483 <struct>JNIEnv</struct>
13484 </outptr>
13485 <description>
13486 The JNI environment of the event (current) thread
13487 </description>
13488 </param>
13489 <param id="thread">
13490 <jthread/>
13491 <description>
13492 Thread allocating the object.
13493 </description>
13494 </param>
13495 <param id="object">
13496 <jobject/>
13497 <description>
13498 JNI local reference to the object that was allocated
13499 </description>
13500 </param>
13501 <param id="object_klass">
13502 <jclass/>
13503 <description>
13504 JNI local reference to the class of the object
13505 </description>
13506 </param>
13507 <param id="size">
13508 <jlong/>
13509 <description>
13510 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13511 </description>
13512 </param>
13513 </parameters>
13514 </event>
13515
13516 <event label="Object Free"
13517 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13518 <description>
|
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 <capabilityfield id="can_generate_sampled_alloc_events" since="11">
10357 <description>
10358 Can generate sampled allocation events.
10359 If this capability is enabled then the heap sampling method
10360 <functionlink id="SetHeapSamplingRate"></functionlink> can be called and the
10361 <eventlink id="SampledObjectAlloc"></eventlink> events can be enabled.
10362 </description>
10363 </capabilityfield>
10364 </capabilitiestypedef>
10365
10366 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10367 <synopsis>Get Potential Capabilities</synopsis>
10368 <description>
10369 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10370 features that can potentially be possessed by this environment
10371 at this time.
10372 The returned capabilities differ from the complete set of capabilities
10373 implemented by the VM in two cases: another environment possesses
10374 capabilities that can only be possessed by one environment, or the
10375 current <functionlink id="GetPhase">phase</functionlink> is live,
10376 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10377 The <functionlink id="AddCapabilities"></functionlink> function
10378 may be used to set any or all or these capabilities.
10379 Currently possessed capabilities are included.
10380 <p/>
10381 Typically this function is used in the <code>OnLoad</code> function.
10382 Some virtual machines may allow a limited set of capabilities to be
10383 added in the live phase.
11522 </constant>
11523 </constants>
11524 </description>
11525 <origin>new</origin>
11526 <capabilities>
11527 </capabilities>
11528 <parameters>
11529 <param id="format_ptr">
11530 <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11531 <description>
11532 On return, points to the format identifier for <code>jlocation</code> values.
11533 </description>
11534 </param>
11535 </parameters>
11536 <errors>
11537 </errors>
11538 </function>
11539
11540 </category>
11541
11542 <category id="heap_monitoring" label="Heap Monitoring">
11543 <function id="SetHeapSamplingRate" phase="onload" num="156" since="11">
11544 <synopsis>Set Heap Sampling Rate</synopsis>
11545 <description>
11546 Set up the allocation system to sample memory allocations at a given
11547 average rate via the <paramlink id="sampling_rate"></paramlink> parameter, defined
11548 by sampling rate in bytes. The
11549 <paramlink id="sampling_rate"></paramlink> will be the average sampling rate in bytes used throughout
11550 the execution.
11551 <p/>
11552 Setting <paramlink id="sampling_rate"></paramlink> to 0 samples each allocation supported by the system.
11553 Combined with a <eventlink id="SampledObjectAlloc"/> event, the Java agent can obtain object allocations with a given sample rate.
11554 </description>
11555 <origin>new</origin>
11556 <capabilities>
11557 <required id="can_generate_sampled_alloc_events"></required>
11558 </capabilities>
11559 <parameters>
11560 <param id="sampling_rate">
11561 <jint/>
11562 <description>
11563 The sampling rate in bytes used for sampling. The sampler will use a statistical approach to
11564 provide in average sampling every <paramlink id="sampling_rate"/> allocated bytes.
11565 <p/>
11566 Passing 0 as a sampling rate provokes a sample per allocation by the system.
11567 <p/>
11568 Note: a low sampling rate, such as sampling every 1024 bytes, will probably incur a high overhead.
11569 Due to the incurred overhead, the sampler should only be used when knowing it may impact performance.
11570 On the other hand, sampling however every 1024kB has a far less chance of a high overhead since it will sample
11571 1024 times less than the 1024-byte sampling.
11572 </description>
11573 </param>
11574 </parameters>
11575 <errors>
11576 <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11577 <paramlink id="sampling_rate"></paramlink> is less than zero.
11578 </error>
11579 </errors>
11580 </function>
11581 </category>
11582
11583 </functionsection>
11584
11585 <errorsection label="Error Reference">
11586 <intro>
11587 Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11588 <p/>
11589 It is the responsibility of the agent to call <jvmti/> functions with
11590 valid parameters and in the proper context (calling thread is attached,
11591 phase is correct, etc.).
11592 Detecting some error conditions may be difficult, inefficient, or
11593 impossible for an implementation.
11594 The errors listed in
11595 <internallink id="reqerrors">Function Specific Required Errors</internallink>
11596 must be detected by the implementation.
11597 All other errors represent the recommended response to the error
11598 condition.
11599 </intro>
11600
11601 <errorcategory id="universal-error" label="Universal Errors">
11602 <intro>
13527 <required id="can_generate_vm_object_alloc_events"></required>
13528 </capabilities>
13529 <parameters>
13530 <param id="jni_env">
13531 <outptr>
13532 <struct>JNIEnv</struct>
13533 </outptr>
13534 <description>
13535 The JNI environment of the event (current) thread
13536 </description>
13537 </param>
13538 <param id="thread">
13539 <jthread/>
13540 <description>
13541 Thread allocating the object.
13542 </description>
13543 </param>
13544 <param id="object">
13545 <jobject/>
13546 <description>
13547 JNI local reference to the object that was allocated.
13548 </description>
13549 </param>
13550 <param id="object_klass">
13551 <jclass/>
13552 <description>
13553 JNI local reference to the class of the object.
13554 </description>
13555 </param>
13556 <param id="size">
13557 <jlong/>
13558 <description>
13559 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13560 </description>
13561 </param>
13562 </parameters>
13563 </event>
13564
13565 <event label="Sampled Object Allocation"
13566 id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" filtered="thread" since="11">
13567 <description>
13568 Sent when an allocated object is sampled.
13569 By default, the sampling rate used is geometric variable with a 512kb mean, meaning one object every 512k bytes,
13570 in average, per thread will
13571 provoke a callback. Each thread having its own internal allocation count, each thread will be sampling
13572 at the same default rate of 512kb.
13573 <p/>
13574 If another sampling rate is required, the user can call
13575 <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value, representing
13576 the new sampling rate to be used by the default sampler.
13577 <p/>
13578 This event is sent once the sampled allocation has been done and provides the object, stack trace
13579 for the allocation, the thread allocating, the size of allocation, and class.
13580 <p/>
13581 Typical use cases of this system is to determine where most heap allocation are originating from.
13582 Using this in conjunction of weak references and the function
13583 <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
13584 stacktrace and which are still live during the execution of the program.
13585 </description>
13586 <origin>new</origin>
13587 <capabilities>
13588 <required id="can_generate_sampled_alloc_events"></required>
13589 </capabilities>
13590 <parameters>
13591 <param id="jni_env">
13592 <outptr>
13593 <struct>JNIEnv</struct>
13594 </outptr>
13595 <description>
13596 The JNI environment of the event (current) thread.
13597 </description>
13598 </param>
13599 <param id="thread">
13600 <jthread/>
13601 <description>
13602 Thread allocating the object.
13603 </description>
13604 </param>
13605 <param id="object">
13606 <jobject/>
13607 <description>
13608 JNI local reference to the object that was allocated.
13609 </description>
13610 </param>
13611 <param id="object_klass">
13612 <jclass/>
13613 <description>
13614 JNI local reference to the class of the object
13615 </description>
13616 </param>
13617 <param id="size">
13618 <jlong/>
13619 <description>
13620 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13621 </description>
13622 </param>
13623 </parameters>
13624 </event>
13625
13626 <event label="Object Free"
13627 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13628 <description>
|