From 0e7496e1633dd4bb2190282daa92d5e431008e21 Mon Sep 17 00:00:00 2001 From: Yavdhesh Sanchihar Date: Fri, 13 Nov 2026 04:37:12 +0000 Subject: [PATCH] feat(core): run user threads on virtual threads (opt-in) Add JMeterThreadFactory, used by ThreadGroup at the two places where threads for JMeterThreads are created. With the new property jmeterthread.use_virtual_threads=true and a Java 21+ runtime, each virtual user runs on its own virtual thread instead of a platform thread, reducing per-user thread memory and context switching for blocking workloads (HTTP waits, timers, JDBC). The feature is opt-in and off by default. JMeter is compiled with --release 17, so the virtual-thread API is used reflectively and the factory falls back to platform threads on Java 17, or if creation fails, preserving current behaviour. Threads are still dedicated, never pooled, so ThreadLocal-based JMeterContext semantics are unchanged. The delayed-start path no longer calls setDaemon(false) on virtual threads (they are always daemon; the engine waits for user threads explicitly via waitThreadsStopped). Adds TestJMeterThreadFactory covering: platform threads by default and when the property is false, virtual threads when enabled on Java 21, and interrupt/join behaviour on virtual threads. --- bin/jmeter.properties | 10 + .../jmeter/threads/JMeterThreadFactory.java | 171 ++++++++++++++++++ .../apache/jmeter/threads/ThreadGroup.java | 11 +- .../threads/TestJMeterThreadFactory.java | 133 ++++++++++++++ 4 files changed, 322 insertions(+), 3 deletions(-) create mode 100644 src/core/src/main/java/org/apache/jmeter/threads/JMeterThreadFactory.java create mode 100644 src/core/src/test/java/org/apache/jmeter/threads/TestJMeterThreadFactory.java diff --git a/bin/jmeter.properties b/bin/jmeter.properties index d25be9de279..d84d2cd451c 100644 --- a/bin/jmeter.properties +++ b/bin/jmeter.properties @@ -1241,6 +1241,16 @@ cookies=cookies # How often to check for shutdown during ramp-up (milliseconds) #jmeterthread.rampup.granularity=1000 +# Run JMeter user threads (one per virtual user) on Java 21 virtual threads instead of +# platform (OS) threads. This can substantially reduce thread memory and context-switching +# overhead for tests whose user threads mostly wait (HTTP responses, timers, JDBC), allowing +# more concurrent virtual users per load generator. It does not speed up CPU-bound samplers. +# Requires Java 21+; on older JVMs the setting is ignored and platform threads are used. +# Disabled by default. Note: virtual threads are always daemon threads, and on Java 21 a +# virtual thread that holds a monitor (synchronized) while blocking may pin its carrier +# thread; watch for jdk.VirtualThreadPinned events in JFR when enabling this. +#jmeterthread.use_virtual_threads=false + #Should JMeter expand the tree when loading a test plan? # default value is false since JMeter 2.7 #onload.expandtree=false diff --git a/src/core/src/main/java/org/apache/jmeter/threads/JMeterThreadFactory.java b/src/core/src/main/java/org/apache/jmeter/threads/JMeterThreadFactory.java new file mode 100644 index 00000000000..b464f14e3f4 --- /dev/null +++ b/src/core/src/main/java/org/apache/jmeter/threads/JMeterThreadFactory.java @@ -0,0 +1,171 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.jmeter.threads; + +import java.lang.reflect.Method; + +import org.apache.jmeter.util.JMeterUtils; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * Creates the {@link Thread} instances that run {@link JMeterThread}s. + * + *

By default this creates ordinary platform threads, exactly as JMeter has always done. + * When the property {@value #USE_VIRTUAL_THREADS_PROPERTY} is set to {@code true} and the + * JVM supports virtual threads (Java 21+), the user threads are created as virtual threads + * instead. One dedicated thread is still created per {@code JMeterThread}: threads are never + * pooled or shared between virtual users, so {@code ThreadLocal}-based state (for instance + * {@link JMeterContextService}) keeps its current semantics.

+ * + *

JMeter is compiled for Java 17, so the Java 21 virtual-thread APIs + * ({@code Thread.ofVirtual()}, {@code Thread.isVirtual()}) are accessed reflectively. + * On Java 17, or when reflective creation fails (for instance on a preview runtime + * without {@code --enable-preview}), the factory silently falls back to platform threads, + * apart from a one-time warning.

+ * + *

Note that virtual threads are always daemon threads, and a virtual thread that holds + * a monitor while performing blocking I/O may pin its carrier thread on Java 21. + * That is one of the reasons this feature is opt-in.

+ */ +public final class JMeterThreadFactory { + + private static final Logger log = LoggerFactory.getLogger(JMeterThreadFactory.class); + + /** Property that enables running JMeter user threads on virtual threads. */ + public static final String USE_VIRTUAL_THREADS_PROPERTY = "jmeterthread.use_virtual_threads"; // $NON-NLS-1$ + + // Reflective handles for the Java 21 virtual thread API, null when unavailable. + private static final Method OF_VIRTUAL_METHOD = lookupOfVirtualMethod(); + private static final Method BUILDER_NAME_METHOD = lookupBuilderMethod("name", String.class); // $NON-NLS-1$ + private static final Method BUILDER_UNSTARTED_METHOD = lookupBuilderMethod("unstarted", Runnable.class); // $NON-NLS-1$ + private static final Method IS_VIRTUAL_METHOD = lookupIsVirtualMethod(); + + private static volatile boolean warnedVirtualThreadsUnavailable; + + private JMeterThreadFactory() { + // utility class + } + + /** + * @return {@code true} when the opt-in property is set. Read dynamically on purpose: + * thread creation is not a hot path, and dynamic reads keep tests and GUI + * property changes simple. + */ + public static boolean isVirtualThreadsEnabled() { + return JMeterUtils.getPropDefault(USE_VIRTUAL_THREADS_PROPERTY, false); + } + + /** + * @return {@code true} when the current JVM offers the Java 21 virtual thread API. + */ + public static boolean isVirtualThreadsSupported() { + return OF_VIRTUAL_METHOD != null && BUILDER_NAME_METHOD != null && BUILDER_UNSTARTED_METHOD != null; + } + + /** + * Creates an unstarted thread for the given workload. + * + * @param runnable the workload, typically a {@link JMeterThread} + * @param name the thread name, preserved for both platform and virtual threads + * @return an unstarted platform thread, or an unstarted virtual thread when virtual + * threads are enabled, supported, and creation succeeds + */ + public static Thread newThread(Runnable runnable, String name) { + if (isVirtualThreadsEnabled()) { + Thread virtualThread = newVirtualThread(runnable, name); + if (virtualThread != null) { + return virtualThread; + } + } + return new Thread(runnable, name); + } + + /** + * Reflective {@code Thread.isVirtual()} that also works when running on Java 17. + * + * @param thread the thread to inspect + * @return {@code true} when the thread is a virtual thread, {@code false} otherwise + * (including on JVMs without virtual thread support) + */ + public static boolean isVirtual(Thread thread) { + if (thread == null || IS_VIRTUAL_METHOD == null) { + return false; + } + try { + return Boolean.TRUE.equals(IS_VIRTUAL_METHOD.invoke(thread)); + } catch (ReflectiveOperationException | RuntimeException e) { + return false; + } + } + + private static Thread newVirtualThread(Runnable runnable, String name) { + if (!isVirtualThreadsSupported()) { + warnUnavailableOnce(); + return null; + } + try { + Object builder = OF_VIRTUAL_METHOD.invoke(null); + Object namedBuilder = BUILDER_NAME_METHOD.invoke(builder, name); + return (Thread) BUILDER_UNSTARTED_METHOD.invoke(namedBuilder, runnable); + } catch (ReflectiveOperationException | RuntimeException e) { + // For instance, virtual threads are a preview feature on Java 19/20 and + // creating one without --enable-preview fails. Fall back to a platform thread. + if (log.isWarnEnabled()) { + log.warn("Could not create a virtual thread, falling back to a platform thread", e); + } + return null; + } + } + + private static void warnUnavailableOnce() { + if (!warnedVirtualThreadsUnavailable) { + warnedVirtualThreadsUnavailable = true; + if (log.isWarnEnabled()) { + log.warn("{}=true, but virtual threads are not available on this JVM " + + "(Java 21+ is required); user threads will run on platform threads", + USE_VIRTUAL_THREADS_PROPERTY); + } + } + } + + private static Method lookupOfVirtualMethod() { + try { + return Thread.class.getMethod("ofVirtual"); // $NON-NLS-1$ + } catch (NoSuchMethodException | RuntimeException e) { + return null; + } + } + + private static Method lookupBuilderMethod(String methodName, Class argumentType) { + try { + Class ofVirtualBuilder = Class.forName("java.lang.Thread$Builder$OfVirtual"); // $NON-NLS-1$ + return ofVirtualBuilder.getMethod(methodName, argumentType); + } catch (ClassNotFoundException | NoSuchMethodException | RuntimeException e) { + return null; + } + } + + private static Method lookupIsVirtualMethod() { + try { + return Thread.class.getMethod("isVirtual"); // $NON-NLS-1$ + } catch (NoSuchMethodException | RuntimeException e) { + return null; + } + } +} diff --git a/src/core/src/main/java/org/apache/jmeter/threads/ThreadGroup.java b/src/core/src/main/java/org/apache/jmeter/threads/ThreadGroup.java index 9599fe0e1c4..ad61fd0c5c0 100644 --- a/src/core/src/main/java/org/apache/jmeter/threads/ThreadGroup.java +++ b/src/core/src/main/java/org/apache/jmeter/threads/ThreadGroup.java @@ -273,7 +273,7 @@ private JMeterThread startNewThread(ListenerNotifier notifier, ListedHashTree th JMeterThread jmThread = makeThread(engine, this, notifier, groupNumber, threadNum, cloneTree(threadGroupTree), variables); scheduleThread(jmThread, now); // set start and end time jmThread.setInitialDelay(delay); - Thread newThread = new Thread(jmThread, jmThread.getThreadName()); + Thread newThread = JMeterThreadFactory.newThread(jmThread, jmThread.getThreadName()); registerStartedThread(jmThread, newThread); newThread.start(); return jmThread; @@ -587,8 +587,13 @@ public void run() { jmThread.setScheduled(true); jmThread.setEndTime(endtime); } - Thread newThread = new Thread(jmThread, jmThread.getThreadName()); - newThread.setDaemon(false); // ThreadStarter is daemon, but we don't want sampler threads to be so too + Thread newThread = JMeterThreadFactory.newThread(jmThread, jmThread.getThreadName()); + // Virtual threads are always daemon threads, and setDaemon(false) is not legal for them. + // The engine waits for user threads explicitly (see waitThreadsStopped), so it does not + // rely on user threads being non-daemon to keep the JVM alive. + if (!JMeterThreadFactory.isVirtual(newThread)) { + newThread.setDaemon(false); // ThreadStarter is daemon, but we don't want sampler threads to be so too + } registerStartedThread(jmThread, newThread); newThread.start(); } diff --git a/src/core/src/test/java/org/apache/jmeter/threads/TestJMeterThreadFactory.java b/src/core/src/test/java/org/apache/jmeter/threads/TestJMeterThreadFactory.java new file mode 100644 index 00000000000..9a138009d3e --- /dev/null +++ b/src/core/src/test/java/org/apache/jmeter/threads/TestJMeterThreadFactory.java @@ -0,0 +1,133 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.jmeter.threads; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; + +import org.apache.jmeter.junit.JMeterTestCase; +import org.apache.jmeter.util.JMeterUtils; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +class TestJMeterThreadFactory extends JMeterTestCase { + + private String previousPropertyValue; + + @BeforeEach + void rememberProperty() { + previousPropertyValue = JMeterUtils.getProperty(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY); + } + + @AfterEach + void restoreProperty() { + if (previousPropertyValue == null) { + JMeterUtils.getJMeterProperties().remove(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY); + } else { + JMeterUtils.setProperty(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY, previousPropertyValue); + } + } + + @Test + void platformThreadIsUsedByDefault() throws Exception { + JMeterUtils.getJMeterProperties().remove(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY); + assertFalse(JMeterThreadFactory.isVirtualThreadsEnabled()); + + AtomicReference executingThread = new AtomicReference<>(); + Thread thread = JMeterThreadFactory.newThread( + () -> executingThread.set(Thread.currentThread()), "platform-user-thread"); + assertEquals("platform-user-thread", thread.getName()); + assertFalse(JMeterThreadFactory.isVirtual(thread), "thread should not be virtual by default"); + + thread.start(); + thread.join(TimeUnit.SECONDS.toMillis(10)); + assertFalse(thread.isAlive()); + assertEquals(thread, executingThread.get()); + assertFalse(JMeterThreadFactory.isVirtual(executingThread.get())); + } + + @Test + void platformThreadIsUsedWhenPropertyIsFalse() { + JMeterUtils.setProperty(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY, "false"); + Thread thread = JMeterThreadFactory.newThread(() -> { }, "explicit-platform-user-thread"); + assertFalse(JMeterThreadFactory.isVirtual(thread)); + } + + @Test + void virtualThreadIsUsedWhenPropertyIsTrueAndSupported() throws Exception { + assumeTrue(JMeterThreadFactory.isVirtualThreadsSupported(), + "virtual threads require Java 21+"); + JMeterUtils.setProperty(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY, "true"); + assertTrue(JMeterThreadFactory.isVirtualThreadsEnabled()); + + CountDownLatch ran = new CountDownLatch(1); + AtomicReference executingThread = new AtomicReference<>(); + AtomicReference virtualInsideRunnable = new AtomicReference<>(); + Thread thread = JMeterThreadFactory.newThread(() -> { + executingThread.set(Thread.currentThread()); + virtualInsideRunnable.set(JMeterThreadFactory.isVirtual(Thread.currentThread())); + ran.countDown(); + }, "virtual-user-thread"); + + assertEquals("virtual-user-thread", thread.getName()); + assertTrue(JMeterThreadFactory.isVirtual(thread), + "factory should create a virtual thread when the property is enabled"); + assertTrue(thread.isDaemon(), "virtual threads are always daemon threads"); + + thread.start(); + assertTrue(ran.await(10, TimeUnit.SECONDS), "runnable should have been executed"); + thread.join(TimeUnit.SECONDS.toMillis(10)); + assertFalse(thread.isAlive()); + assertEquals(thread, executingThread.get()); + assertEquals(Boolean.TRUE, virtualInsideRunnable.get(), + "the user-thread workload should execute on a virtual thread"); + } + + @Test + void virtualThreadCanBeInterruptedAndJoined() throws Exception { + assumeTrue(JMeterThreadFactory.isVirtualThreadsSupported(), + "virtual threads require Java 21+"); + JMeterUtils.setProperty(JMeterThreadFactory.USE_VIRTUAL_THREADS_PROPERTY, "true"); + + CountDownLatch started = new CountDownLatch(1); + CountDownLatch interrupted = new CountDownLatch(1); + Thread thread = JMeterThreadFactory.newThread(() -> { + started.countDown(); + try { + Thread.sleep(TimeUnit.MINUTES.toMillis(1)); + } catch (InterruptedException e) { + interrupted.countDown(); + } + }, "interruptible-virtual-user-thread"); + + thread.start(); + assertTrue(started.await(10, TimeUnit.SECONDS)); + thread.interrupt(); + assertTrue(interrupted.await(10, TimeUnit.SECONDS), + "interrupt should wake a virtual thread blocked in sleep, as stopThread relies on it"); + thread.join(TimeUnit.SECONDS.toMillis(10)); + assertFalse(thread.isAlive()); + } +}