Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions bin/jmeter.properties
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
*
* <p>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.</p>
*
* <p>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.</p>
*
* <p>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.</p>
*/
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;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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();
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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<Thread> 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<Thread> executingThread = new AtomicReference<>();
AtomicReference<Boolean> 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());
}
}