Summary

Introduce JDK specific MemoryMXBean in com.sun.management and add method com.sun.management.MemoryMXBean.getTotalGcCpuTime(). This method returns the CPU time in nanoseconds for all GC related threads and the GC related operations on the VM thread.

Problem

The VM supports retrieval of GC CPU time since JDK 26 (JDK-8359110) and logs these values via -Xlog:cpu during VM shutdown. To support a refined understanding, during critical sections, of GC CPU time, sampling this at will would be needed. There is no viable alternative to sample this from Java application code today. This will complement getProcessCpuTime() from com.sun.management.OperatingSystemMXBean.

Solution

Although GarbageCollectorMXBean might seem like the best fit, it is not a singleton which makes it ill-suited for something that applies for the GC as a whole. The proposed solution is to introduce a new JDK specific MemoryMXBean in com.sun.management along with a method getTotalGcCpuTime().

Specification

/**
 * Platform-specific management interface for the memory
 * system on which the Java virtual machine is running.
 *
 * @since 26
 */

public interface MemoryMXBean extends java.lang.management.MemoryMXBean {
    /**
     * Returns the CPU time used by garbage collection.
     *
     * <p> Samples accumulated CPU time used by all garbage collection.
     * In general this includes time for all driver threads,
     * workers, VM operations on the VM thread and the string
     * deduplication thread (if enabled). May be non-zero even if no
     * GC cycle occurred. This method returns {@code -1} if the
     * platform does not support this operation or if called during
     * shutdown.
     *
     * May be used in conjunction with {@link com.sun.management.OperatingSystemMXBean#getProcessCpuTime()}
     * for calculating the GC's usage of CPU time as a whole.
     *
     * @return the total accumulated CPU time for garbage collection
     * in nanoseconds.
     *
     * @since 26
     */
    public long getTotalGcCpuTime();
}