Generate ajvmtiError SetHeapSamplingRate(jvmtiEnv* env, jint sampling_rate)
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_rate
since the last sample.
Setting sampling_rate
to 0 will cause an event to be
generated by each allocation supported by the system.
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
SetHeapSamplingRate can be
called and SampledObjectAlloc events can be generated.
|
Parameters | ||
Name | Type | Description |
sampling_rate | jint |
The sampling rate in bytes. The sampler uses a statistical approach to
generate an event, on average, once for every sampling_rate bytes of
memory allocated by a given thread.
Passing 0 as a sampling rate generates a sample for every allocation.
Note: The overhead of this feature is directly correlated with the sampling rate.
A high sampling rate, such as 1024 bytes, will incur a high overhead.
A lower rate, 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_rate is less than zero.
|
Sent when an allocated object is sampled. By default, the sampling rate is a geometric variable with a 512KB mean. Each thread tracks how many bytes it has allocated since it sent the last event. When the number of bytes exceeds the sampling rate, 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 this is a geometric variable: 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 rate is required, the user can callvoid JNICALL SampledObjectAlloc(jvmtiEnv *jvmti_env, JNIEnv* jni_env, jthread thread, jobject object, jclass object_klass, jlong size)
SetHeapSamplingRate
with a strictly positive integer value, representing
the new sampling rate.
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
SetHeapSamplingRate 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 .
|