< prev index next >


Print this page
rev 50392 : JEP 331

*** 10351,10360 **** --- 10351,10368 ---- are enabled then the <eventlink id="ClassFileLoadHook"/> events can be posted for classes loaded in the primordial phase. See <eventlink id="ClassFileLoadHook"/>. </description> </capabilityfield> + <capabilityfield id="can_generate_sampled_object_alloc_events" since="11"> + <description> + Can generate sampled allocation events. + If this capability is enabled then the heap sampling method + <functionlink id="SetHeapSamplingRate"></functionlink> can be + called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated. + </description> + </capabilityfield> </capabilitiestypedef> <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140"> <synopsis>Get Potential Capabilities</synopsis> <description>
*** 11529,11538 **** --- 11537,11587 ---- </errors> </function> </category> + <category id="heap_monitoring" label="Heap Monitoring"> + <function id="SetHeapSamplingRate" phase="onload" num="156" since="11"> + <synopsis>Set Heap Sampling Rate</synopsis> + <description> + Generate a <eventlink id="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 <paramlink id="sampling_rate"></paramlink> + since the last sample. + <p/> + Setting <paramlink id="sampling_rate"></paramlink> to 0 will cause an event to be + generated by each allocation supported by the system. + </description> + <origin>new</origin> + <capabilities> + <required id="can_generate_sampled_object_alloc_events"></required> + </capabilities> + <parameters> + <param id="sampling_rate"> + <jint/> + <description> + The sampling rate in bytes. The sampler uses a statistical approach to + generate an event, on average, once for every <paramlink id="sampling_rate"/> bytes of + memory allocated by a given thread. + <p/> + Passing 0 as a sampling rate generates a sample for every allocation. + <p/> + 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. + </description> + </param> + </parameters> + <errors> + <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> + <paramlink id="sampling_rate"></paramlink> is less than zero. + </error> + </errors> + </function> + </category> + </functionsection> <errorsection label="Error Reference"> <intro> Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
*** 13493,13503 **** </description> </param> <param id="object"> <jobject/> <description> ! JNI local reference to the object that was allocated </description> </param> <param id="object_klass"> <jclass/> <description> --- 13542,13619 ---- </description> </param> <param id="object"> <jobject/> <description> ! JNI local reference to the object that was allocated. ! </description> ! </param> ! <param id="object_klass"> ! <jclass/> ! <description> ! JNI local reference to the class of the object. ! </description> ! </param> ! <param id="size"> ! <jlong/> ! <description> ! Size of the object (in bytes). See <functionlink id="GetObjectSize"/>. ! </description> ! </param> ! </parameters> ! </event> ! ! <event label="Sampled Object Allocation" ! id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11"> ! <description> ! 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. ! <p/> ! 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). ! <p/> ! If another sampling rate is required, the user can call ! <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value, representing ! the new sampling rate. ! <p/> ! 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. ! <p/> ! A typical use case of this system is to determine where heap allocations originate. ! In conjunction with weak references and the function ! <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which ! stack trace, and which are still live during the execution of the program. ! </description> ! <origin>new</origin> ! <capabilities> ! <required id="can_generate_sampled_object_alloc_events"></required> ! </capabilities> ! <parameters> ! <param id="jni_env"> ! <outptr> ! <struct>JNIEnv</struct> ! </outptr> ! <description> ! The JNI environment of the event (current) thread. ! </description> ! </param> ! <param id="thread"> ! <jthread/> ! <description> ! Thread allocating the object. ! </description> ! </param> ! <param id="object"> ! <jobject/> ! <description> ! JNI local reference to the object that was allocated. </description> </param> <param id="object_klass"> <jclass/> <description>
< prev index next >