Use virtual threads in REST applications

In this guide, we see how you can use virtual threads in a REST application. Because virtual threads are all about I/O, we will also use the REST client.

先决条件

要完成这个指南,你需要:

  • 大概15分钟

  • 编辑器

  • JDK 21+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.9.16

  • 如果你愿意的话,还可以选择使用Quarkus CLI

  • 如果你想构建原生可执行程序,可以选择安装Mandrel或者GraalVM,并正确配置(或者使用Docker在容器中进行构建)

应用结构

The application built into this guide is quite simple. It calls a weather service for two cities (Valence, France, and Athens, Greece) and decides the best place based on the current temperature.

Create the Maven project

首先,我们需要一个新的项目。使用以下命令创建一个新的项目:

CLI
quarkus create app org.acme:rest-virtual-threads \
    --extension='rest-jackson,quarkus-rest-client-jackson' \
    --no-code
cd rest-virtual-threads

创建Grade项目,请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven
mvn io.quarkus:quarkus-maven-plugin:999-SNAPSHOT:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=rest-virtual-threads \
    -Dextensions='rest-jackson,quarkus-rest-client-jackson' \
    -DnoCode
cd rest-virtual-threads

创建Grade项目,请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

For Windows users:

  • If using cmd, (don’t use backward slash \ and put everything on the same line)

  • If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=rest-virtual-threads"

This command generates a new project importing the Quarkus REST (formerly RESTEasy Reactive), REST client, and Jackson extensions, and in particular, adds the following dependencies:

pom.xml
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-rest-jackson</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-rest-client-jackson</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-rest-jackson")
implementation("io.quarkus:quarkus-rest-client-jackson")

You might wonder why we use reactive extensions. Virtual threads have limitations, and we can only integrate them properly when using the reactive extensions. No worries: your code will be written 100% in a synchronous / imperative style.

Check the virtual thread reference guide for details.

Prepare the pom.xml file

We need to customize the pom.xml file to use virtual threads.

1) Check that the maven.compiler.release property is 21 or later:

    <maven.compiler.release>21</maven.compiler.release>

2) In the maven-surefire-plugin and maven-failsafe-plugin configurations, add the following argLine parameter:

The -Djdk.tracePinnedThreads system property only works on Java 21-23. It has been removed in Java 24+. For Java 24+, use the JFR events or Quarkus testing extensions instead (see the Testing virtual thread applications section).
<plugin>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>${surefire-plugin.version}</version>
  <configuration>
    <systemPropertyVariables>
      <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
      <maven.home>${maven.home}</maven.home>
    </systemPropertyVariables>
    <argLine>-Djdk.tracePinnedThreads</argLine> <!-- Added line - only works on Java 21-23 -->
  </configuration>
</plugin>
<plugin>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>${surefire-plugin.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
      <configuration>
        <systemPropertyVariables>
          <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
          <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
          <maven.home>${maven.home}</maven.home>
        </systemPropertyVariables>
        <argLine>-Djdk.tracePinnedThreads</argLine> <!-- Added line - only works on Java 21-23 -->
      </configuration>
    </execution>
  </executions>
</plugin>

The -Djdk.tracePinnedThreads will detect pinned carrier threads while running tests on Java 21-23 (See the virtual thread reference guide for details).

--enable-preview on Java 19 and 20

If you are using a Java 19 or 20, add the --enable-preview flag in the argLine and as parameters of the maven compiler plugin. Note that we strongly recommend Java 21.

Create the weather client

This section is not about virtual threads. Because we need to do some I/O to demonstrate virtual threads usage, we need a client doing I/O operations. In addition, the REST client is virtual thread friendly: it does not pin and handle propagation correctly.

Create the src/main/java/org/acme/WeatherService.java class with the following content:

package org.acme;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.quarkus.rest.client.reactive.ClientQueryParam;
import jakarta.ws.rs.GET;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.reactive.RestQuery;

@RegisterRestClient(baseUri = "https://api.open-meteo.com/v1/forecast")
public interface WeatherService {

    @GET
    @ClientQueryParam(name = "current_weather", value = "true")
    WeatherResponse getWeather(@RestQuery double latitude, @RestQuery double longitude);


    record WeatherResponse(@JsonProperty("current_weather") Weather weather) {
        // represents the response
    }

    record Weather(double temperature, double windspeed) {
        // represents the inner object
    }
}

This class models the HTTP interaction with the weather service. Read more about the rest client in the dedicated guide.

Create the HTTP endpoint

Now, create the src/main/java/org/acme/TheBestPlaceToBeResource.java class with the following content:

package org.acme;

import io.smallrye.common.annotation.RunOnVirtualThread;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.eclipse.microprofile.rest.client.inject.RestClient;

@Path("/")
public class TheBestPlaceToBeResource {

    static final double VALENCE_LATITUDE = 44.9;
    static final double VALENCE_LONGITUDE = 4.9;

    static final double ATHENS_LATITUDE = 37.9;
    static final double ATHENS_LONGITUDE = 23.7;

    @RestClient WeatherService service;

    @GET
    @RunOnVirtualThread (1)
    public String getTheBestPlaceToBe() {
        var valence = service.getWeather(VALENCE_LATITUDE, VALENCE_LONGITUDE).weather().temperature();
        var athens = service.getWeather(ATHENS_LATITUDE, ATHENS_LONGITUDE).weather().temperature();

        // Advanced decision tree
        if (valence > athens && valence <= 35) {
            return "Valence! (" + Thread.currentThread() + ")";
        } else if (athens > 35) {
            return "Valence! (" + Thread.currentThread() + ")";
        } else {
            return "Athens (" + Thread.currentThread() + ")";
        }
    }
}
1 Instructs Quarkus to invoke this method on a virtual thread

Run the application in dev mode

Make sure that you use OpenJDK and JVM versions supporting virtual thread and launch the dev mode with ./mvnw quarkus:dev:

> java --version
openjdk 21 2023-09-19 LTS (1)
OpenJDK Runtime Environment Temurin-21+35 (build 21+35-LTS)
OpenJDK 64-Bit Server VM Temurin-21+35 (build 21+35-LTS, mixed mode)

> ./mvnw quarkus:dev (2)
1 Must be 19+, we recommend 21+
2 Launch the dev mode

Then, in a browser, open http://localhost:8080. You should get something like:

Valence! (VirtualThread[#144]/runnable@ForkJoinPool-1-worker-6)

As you can see, the endpoint runs on a virtual thread.

It’s essential to understand what happened behind the scene:

  1. Quarkus creates the virtual thread to invoke your endpoint (because of the @RunOnVirtualThread annotation).

  2. When the code invokes the rest client, the virtual thread is blocked, BUT the carrier thread is not blocked (that’s the virtual thread magic touch).

  3. Once the first invocation of the rest client completes, the virtual thread is rescheduled and continues its execution.

  4. The second rest client invocation happens, and the virtual thread is blocked again (but not the carrier thread).

  5. Finally, when the second invocation of the rest client completes, the virtual thread is rescheduled and continues its execution.

  6. The method returns the result. The virtual thread terminates.

  7. The result is captured by Quarkus and written in the HTTP response

Use virtual threads for every endpoint

Annotating every endpoint with @RunOnVirtualThread can be cumbersome when you want your whole application to use virtual threads. There are two ways to switch the default execution model for all endpoints at once: a configuration property and an annotated Quarkus REST Application class.

Before switching all endpoints to virtual threads, make sure your application and its dependencies do not suffer from thread pinning or carrier thread monopolization. For more information, see the Quarkus Virtual thread support reference guide. Thread pinning caused by synchronized blocks is resolved in JDK 24 and later, so we recommend running on JDK 24 or later when enabling virtual threads globally. You can detect pinning in your tests, as shown in the section below.

Use the configuration property

You can enable virtual threads for all Quarkus REST endpoints with a single build-time property:

quarkus.rest.blocking.signatures.execution.mode=virtual-thread

When enabled, every endpoint that would otherwise be executed on a worker thread is executed on a virtual thread instead. The regular execution model rules still apply:

  • Endpoints considered non-blocking because they return Uni, Multi or CompletionStage keep running on the event loop.

  • Explicit @Blocking, @NonBlocking and @RunOnVirtualThread annotations on the endpoint method or resource class always take precedence. So, if a specific endpoint is not safe to run on a virtual thread, annotate it with @Blocking to keep it on a worker thread.

  • An execution model annotation on the Quarkus REST Application class takes precedence over this property, and a warning is logged at startup.

Annotate the Quarkus REST Application class

Alternatively, you can declare the default execution model in code. Quarkus does not require a Quarkus REST Application class, but you can add one and annotate it with @RunOnVirtualThread:

package org.acme;

import jakarta.ws.rs.core.Application;

import io.smallrye.common.annotation.RunOnVirtualThread;

@RunOnVirtualThread
public class MyApplication extends Application {
}

Every endpoint without an explicit @Blocking annotation is then executed on a virtual thread. Unlike the configuration property, this approach also moves endpoints with a non-blocking signature, such as endpoints returning Uni, to a virtual thread. The same applies to endpoints annotated with @NonBlocking; in this case, a warning is logged at startup. An application can only have one Application class.

Choose between the two approaches

The following table summarizes on which thread an endpoint is executed, depending on how it is declared:

Table 1. Execution model depending on the endpoint declaration
Endpoint 默认 quarkus.rest.blocking.signatures.execution.mode=virtual-thread @RunOnVirtualThread on Application

No annotation, blocking signature (returns String, a POJO, …​)

Worker thread

Virtual thread

Virtual thread

No annotation, non-blocking signature (returns Uni, Multi, CompletionStage, …​)

Event loop

Event loop

Virtual thread

@Blocking

Worker thread

Worker thread

Worker thread

@NonBlocking

Event loop

Event loop

Virtual thread (a warning is logged)

@RunOnVirtualThread

Virtual thread

Virtual thread

Virtual thread

Revert to worker threads without code changes

If you run into problems, you do not need to remove the property or the annotation to compare against the worker thread model. Setting quarkus.virtual-threads.enabled=false executes all the endpoints marked to run on virtual threads on worker threads instead.

Verify pinning using tests

In the pom.xml, we added an argLine argument to the surefire and failsafe plugins:

<argLine>-Djdk.tracePinnedThreads</argLine> <!-- Only works on Java 21-23 -->

The -Djdk.tracePinnedThreads dumps the stack trace if a virtual thread cannot be unmounted smoothly (meaning that it blocks the carrier thread). That’s what we call pinning (more info in the virtual thread reference guide).

This flag only works on Java 21-23 and has been removed in Java 24+. For Java 24+, use the Quarkus junit-virtual-threads extension described in the virtual thread reference guide, which uses JFR events to detect pinning across all Java versions.
Starting with Java 24, thanks to JEP 491, synchronized blocks no longer cause pinning. This means pinning is much less likely to occur on Java 24+, occurring only when native code calls back to Java code that performs blocking operations.

We recommend enabling pinning detection in tests. Thus, you can check that your application behaves correctly when using virtual threads. Just check your log after having run the test. If you see a stack trace (on Java 21-23) or pinning events (using the junit-virtual-threads extension), better check what’s wrong. If your code (or one of your dependencies) pins, it might be better to use regular worker threads instead.

Create the src/test/java/org/acme/TheBestPlaceToBeResourceTest.java class with the following content:

package org.acme;

import io.quarkus.test.junit.QuarkusTest;
import io.restassured.RestAssured;
import org.junit.jupiter.api.Test;

@QuarkusTest
class TheBestPlaceToBeResourceTest {

    @Test
    void verify() {
        RestAssured.get("/")
                .then()
                .statusCode(200);
    }

}

It is a straightforward test, but at least it will detect if our application is pinning. Run the test with either:

  • r in dev mode (using continuous testing)

  • ./mvnw test

As you will see, it does not pin - no stack trace. It is because the REST client is implemented in a virtual-thread-friendly way.

The same approach can be used with integration tests.

解决方案

This guide shows how you can use virtual threads with Quarkus REST and the REST client. Learn more about virtual threads support on: