jvmtiError
SetHeapSamplingInterval(jvmtiEnv* env,
jint sampling_interval)
Generate a SampledObjectAlloc event when objects are allocated.
Each thread keeps a counter of bytes allocated. The event will only be generated
when that counter exceeds an average of sampling_interval
since the last sample.
Setting sampling_interval to 0 will cause an event to be
generated by each allocation supported by the system once the new interval is taken into account.
Note that updating the new sampling interval might take various number of allocations
to provoke internal data structure updates. Therefore it is important to
consider the sampling interval as an average. This includes the interval 0, where events
might not be generated straight away for each allocation.
| Phase | Callback Safe | Position | Since |
| may only be called during the OnLoad or the live phase | No | 156 | 11 |
| Capabilities | |
Optional Functionality: might not be implemented for all
virtual machines.
The following capability
(as returned by
GetCapabilities)
must be true to use this
function.
|
|
| Capability | Effect |
can_generate_sampled_object_alloc_events |
Can generate sampled allocation events.
If this capability is enabled then the heap sampling method
SetHeapSamplingInterval can be
called and SampledObjectAlloc events can be generated.
|
| Parameters | ||
| Name | Type | Description |
sampling_interval | jint |
The sampling interval in bytes. The sampler uses a statistical approach to
generate an event, on average, once for every sampling_interval bytes of
memory allocated by a given thread.
Once the new sampling interval is taken into account, 0 as a sampling interval will generate
a sample for every allocation.
Note: The overhead of this feature is directly correlated with the sampling interval.
A high sampling interval, such as 1024 bytes, will incur a high overhead.
A lower interval, such as 1024KB, will have a much lower overhead. Sampling should only
be used with an understanding that it may impact performance.
|
| Errors | |
| This function returns either a universal error or one of the following errors | |
| Error | Description |
JVMTI_ERROR_MUST_POSSESS_CAPABILITY
|
The environment does not possess the capability
can_generate_sampled_object_alloc_events.
Use AddCapabilities.
|
JVMTI_ERROR_ILLEGAL_ARGUMENT |
sampling_interval is less than zero.
|
void JNICALL
SampledObjectAlloc(jvmtiEnv *jvmti_env,
JNIEnv* jni_env,
jthread thread,
jobject object,
jclass object_klass,
jlong size)
Sent when an allocated object is sampled.
By default, the sampling interval is set to 512KB. The sampling is semi-random to avoid
pattern-based bias and provides an approximate overall average interval over long periods of
sampling.
Each thread tracks how many bytes it has allocated since it sent the last event.
When the number of bytes exceeds the sampling interval, it will send another event.
This implies that, on average, one object will be sampled every time a thread has
allocated 512KB bytes since the last sample.
Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
The goal of this is to ensure high quality sampling even if allocation is
happening in a fixed pattern (i.e., the same set of objects are being allocated
every 512KB).
If another sampling interval is required, the user can call
SetHeapSamplingInterval with a strictly positive integer value,
representing the new sampling interval.
This event is sent once the sampled allocation has been performed. It provides the object, stack trace
of the allocation, the thread allocating, the size of allocation, and the object's class.
A typical use case of this system is to determine where heap allocations originate.
In conjunction with weak references and the function
GetStackTrace, a user can track which objects were allocated from which
stack trace, and which are still live during the execution of the program.
| Phase | Event Type | Number | Enabling | Since |
| sent only during the live phase | JVMTI_EVENT_SAMPLED_OBJECT_ALLOC | 86 | SetEventNotificationMode(JVMTI_ENABLE,
JVMTI_EVENT_SAMPLED_OBJECT_ALLOC, NULL) | 11 |
| Capabilities | |
Optional Functionality: might not be implemented for all
virtual machines.
The following capability
(as returned by
GetCapabilities)
must be true to use this
event.
|
|
| Capability | Effect |
can_generate_sampled_object_alloc_events |
Can generate sampled allocation events.
If this capability is enabled then the heap sampling method
SetHeapSamplingInterval can be
called and SampledObjectAlloc events can be generated.
|
| Parameters | ||
| Name | Type | Description |
jni_env |
JNIEnv
* | The JNI environment of the event (current) thread. |
thread | jthread | Thread allocating the object. |
object | jobject | JNI local reference to the object that was allocated. |
object_klass | jclass | JNI local reference to the class of the object |
size | jlong |
Size of the object (in bytes). See GetObjectSize.
|