Summary

This is a backport CSR corresponding to JDK-8307396.

Add a new method, com.sun.management.ThreadMXBean.getTotalThreadAllocatedBytes(), which returns an approximation of the total number of bytes allocated by the JVM on the Java heap since JVM launch. The new method's return value includes the amount of memory allocated by both terminated and currently live threads.

Problem

com.sun.management.ThreadMXBean supports per-thread cumulative (since thread start) allocated memory queries via getCurrentThreadAllocatedBytes(), getThreadAllocatedBytes(long) and getThreadAllocatedBytes(long[]). A way to get the same information for the entire JVM process is one of the top requested serviceability enhancements because it enables easy and relatively low cost computation of a JVM's Java heap object allocation rate. The existing alternative of obtaining a thread id list, calling getThreadAllocatedBytes(long []), and summing the result array is cumbersome, slow, and can consume much Java heap memory.

Solution

Define a new com.sun.management.ThreadMXBean method

long getTotalThreadAllocatedBytes()

that returns an approximation of the total number of bytes allocated in the Java heap by the JVM process since launch. The new method is added to com.sun.management.ThreadMXBean because the existing thread allocated memory measurement functionality is defined there. The result being a 64 bit signed value, rollover is possible, but at a 10gb/sec allocation rate would take approximately 27 years to occur.

The new method is a default method whose implementation throws UnsupportedOperationException if the JVM does not support thread memory allocation measurement, and otherwise returns -1 whether or not thread allocated memory measurement is supported. The latter was deemed a simpler approach than, e.g., defining a new exception.

Specification

Add a new method to com.sun.management.ThreadMXBean.

    /**
     * Returns an approximation of the total amount of memory, in bytes, allocated
     * in heap memory by all threads since the Java virtual machine started.
     * The returned value is an approximation because some Java virtual machine
     * implementations may use object allocation mechanisms that result in a
     * delay between the time an object is allocated and the time its size is
     * recorded.
     *
     * @return an approximation of the total memory allocated, in bytes, in
     * heap memory since the Java virtual machine started,
     * if thread memory allocation measurement is enabled;
     * {@code -1} otherwise.
     *
     * @implSpec The default implementation throws {@code UnsupportedOperationException}                                                                                                                                                                                                                                                                                            
     * if the Java virtual machine implementation does not support thread                                                                                                                                                                                                                                                                                                   
     * memory allocation measurement, and otherwise acts as though thread                                                                                                                                                                                                                                                                                                   
     * memory allocation measurement is disabled.                                                                                                                                                                                                                                                                                                                           
     *
     * @throws UnsupportedOperationException if the Java virtual
     *         machine implementation does not support thread memory allocation
     *         measurement.
     *
     * @see #isThreadAllocatedMemorySupported
     * @see #isThreadAllocatedMemoryEnabled
     * @see #setThreadAllocatedMemoryEnabled
     *
     * @since 17.0.10
     */
    public long getTotalThreadAllocatedBytes() {
        if (!isThreadAllocatedMemorySupported()) {
            throw new UnsupportedOperationException(
                "Thread allocated memory measurement is not supported.");
        }
        return -1;
    }