Summary

Introduce a new JDK-specific monitoring and management interface named jdk.management.VirtualThreadSchedulerMXBean to monitor and manage the virtual thread scheduler with JMX based tooling.

Problem

There is currently no monitoring or tooling support that gives insight into the status or threads used by the virtual thread scheduler. Additionally, there is no management interface that allows the tooling to dynamically adjust the resources that the virtual thread scheduler should use.

Solution

Add management interface jdk.management.VirtualThreadSchedulerMXBean to the jdk.management module.

The existing management interfaces in the jdk.management module date from JDK 5/6 and are in the com.sun.management package. The proposed solution introduces the new interface in the jdk.management package, thus establishing a new home for new management interfaces going forward.

Specification

package jdk.management;

import java.lang.management.ManagementFactory;
import java.lang.management.PlatformManagedObject;
import java.util.concurrent.ForkJoinPool;
import javax.management.MBeanServer;
import javax.management.ObjectName;

/**
 * Management interface for the JDK's {@linkplain Thread##virtual-threads virtual thread}
 * scheduler.
 *
 * <p> {@code VirtualThreadSchedulerMXBean} supports monitoring of the virtual thread
 * scheduler's target parallelism, the {@linkplain Thread##platform-threads platform threads}
 * used by the scheduler, and the number of virtual threads queued to the scheduler. It
 * also supports dynamically changing the scheduler's target parallelism.
 *
 * <p> The management interface is registered with the platform {@link MBeanServer
 * MBeanServer}. The {@link ObjectName ObjectName} that uniquely identifies the management
 * interface within the {@code MBeanServer} is: "jdk.management:type=VirtualThreadScheduler".
 *
 * <p> Direct access to the MXBean interface can be obtained with
 * {@link ManagementFactory#getPlatformMXBean(Class)}.
 *
 * @since 24
 */
public interface VirtualThreadSchedulerMXBean extends PlatformManagedObject {

    /**
     * {@return the scheduler's target parallelism}
     *
     * @see ForkJoinPool#getParallelism()
     */
    int getParallelism();

    /**
     * Sets the scheduler's target parallelism.
     *
     * <p> Increasing the target parallelism allows the scheduler to use more platform
     * threads to <i>carry</i> virtual threads if required. Decreasing the target parallelism
     * reduces the number of threads that the scheduler may use to carry virtual threads.
     *
     * @apiNote If virtual threads are mounting and unmounting frequently then downward
     * adjustment of the target parallelism will likely come into effect quickly.
     *
     * @implNote The JDK's virtual thread scheduler is a {@link ForkJoinPool}. Target
     * parallelism defaults to the number of {@linkplain Runtime#availableProcessors()
     * available processors}. The minimum target parallelism is 1, the maximum target
     * parallelism is 32767.
     *
     * @param size the target parallelism level
     * @throws IllegalArgumentException if size is less than the minimum, or
     *         greater than the maximum, supported by the scheduler
     * @throws UnsupportedOperationException if changing the target
     *         parallelism is not suppored by the scheduler
     *
     * @see ForkJoinPool#setParallelism(int)
     */
    void setParallelism(int size);

    /**
     * {@return the current number of platform threads that the scheduler has started
     * but have not terminated; {@code -1} if not known}
     *
     * <p> The count includes the platform threads that are currently <i>carrying</i>
     * virtual threads and the platform threads that are not currently carrying virtual
     * threads. The thread count may be greater than the scheduler's target parallelism.
     *
     * @implNote The JDK's virtual thread scheduler is a {@link ForkJoinPool}. The pool
     * size is the {@linkplain ForkJoinPool#getPoolSize() number of worker threads}.
     */
    int getPoolSize();

    /**
     * {@return an estimate of the number of virtual threads that are currently
     * <i>mounted</i> by the scheduler; {@code -1} if not known}
     *
     * <p> The number of mounted virtual threads is equal to the number of platform
     * threads carrying virtual threads.
     *
     * @implNote This method may overestimate the number of virtual threads that are mounted.
     */
    int getMountedVirtualThreadCount();

    /**
     * {@return an estimate of the number of virtual threads that are queued to
     * the scheduler to start or continue execution; {@code -1} if not known}
     *
     * @implNote This method may overestimate the number of virtual threads that are
     * queued to execute.
     */
    long getQueuedVirtualThreadCount();
}