src/hotspot/share/prims/jvmti.xml

rev 49244 : [mq]: event-only
rev 49245 : [mq]: event3
rev 49246 : [mq]: event4
rev 49247 : [mq]: event5

*** 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_sample_heap" since="11">
+         <description>
+           Can sample the heap.
+           If this capability is enabled then the heap sampling method
+           <functionlink id="SetHeapSamplingRate"></functionlink> can be called and the
+           <eventlink id="SampledObjectAlloc"></eventlink> events can be enabled.
+         </description>
+       </capabilityfield>
      </capabilitiestypedef>
  
      <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
        <synopsis>Get Potential Capabilities</synopsis>
        <description>
*** 11529,11538 ****
--- 11537,11585 ----
        </errors>
      </function>
  
    </category>
  
+   <category id="heap_monitoring" label="Heap Monitoring">
+     <function id="SetHeapSamplingRate" phase="any" num="156" since="11">
+       <synopsis>Set Heap Sampling Rate</synopsis>
+       <description>
+         Set up the allocation system to sample memory at a given
+         average rate via the <paramlink id="sampling_rate"></paramlink> parameter, defined
+         by sampling rate in bytes. The
+         <paramlink id="sampling_rate"></paramlink> will be the average sampling rate in bytes used throughout
+         the execution.
+ 
+         Setting <paramlink id="sampling_rate"></paramlink> to 0 disables the heap sampling.
+         Combined with a <eventlink id="SampledObjectAlloc"/> event, the Java agent can obtain object allocations with a given sample rate.
+       </description>
+       <origin>new</origin>
+       <capabilities>
+         <required id="can_sample_heap"></required>
+       </capabilities>
+       <parameters>
+         <param id="sampling_rate">
+           <jint/>
+           <description>
+             The sampling rate in bytes used for sampling. The sampler will use a statistical approach to
+             provide in average sampling every <paramlink id="sampling_rate"/> allocated bytes.
+ 
+             Note: a low sampling rate, such as sampling every 1024 bytes, will probably incur a high overhead.
+             Due to the incurred overhead, the sampler should only be used when knowing it may impact performance.
+             On the other hand, sampling however every 1024kB has a far less chance of a high overhead since it will sample
+             1024 times less than the 1024-byte sampling.
+           </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>
--- 13540,13606 ----
            </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 Trace"
!     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" num="86" since="11">
!     <description>
!       Sent when an object is sampled via the
!       <internallink id="heap_monitoring"> Heap Sampling Monitoring system </internallink>.
!       Therefore, this event is sent to the user if there is at least one call to
!       <functionlink id="SetHeapSamplingRate"></functionlink> with a strictly positive integer value.
! 
!       The event is sent once the allocation has been done and provides the object, stack trace
!       for the allocation, the thread allocating, the size of allocation, and class.
!       <p/>
!       Typical use cases of this system is to determine where most heap allocation are originating from.
!       Using this in conjunction of weak references and the function
!       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
!       stacktrace and which are still live during the execution of the program.
!     </description>
!     <origin>new</origin>
!     <capabilities>
!       <required id="can_sample_heap"></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>