From 12fd29797f1999419aad42030692cb4eee0b0b1d Mon Sep 17 00:00:00 2001 From: Clement Escoffier Date: Thu, 26 Oct 2023 16:23:13 +0200 Subject: [PATCH] Update virtual thread documentation to Java 21 --- .../main/asciidoc/grpc-virtual-threads.adoc | 21 ++++------ .../asciidoc/messaging-virtual-threads.adoc | 25 ++++------- .../resteasy-reactive-virtual-threads.adoc | 41 ++++++------------- docs/src/main/asciidoc/virtual-threads.adoc | 15 ++++--- 4 files changed, 35 insertions(+), 67 deletions(-) diff --git a/docs/src/main/asciidoc/grpc-virtual-threads.adoc b/docs/src/main/asciidoc/grpc-virtual-threads.adoc index 0b3d657ddb3046..61d805a9fa0b98 100644 --- a/docs/src/main/asciidoc/grpc-virtual-threads.adoc +++ b/docs/src/main/asciidoc/grpc-virtual-threads.adoc @@ -26,7 +26,7 @@ But, you can also use the link:{blocking_annotation}[@Blocking] annotation to in The idea behind Quarkus Virtual Thread support for gRPC services is to offload the service method invocation on virtual threads, instead of running it on an event-loop thread or a worker thread. To enable virtual thread support on a service method, simply add the link:{runonvthread}[@RunOnVirtualThread] annotation to the method. -If the JDK is compatible (Java 19 or later versions) then the invocation will be offloaded to a new virtual thread. +If the JDK is compatible (Java 19 or later versions - we recommend 21+) then the invocation will be offloaded to a new virtual thread. It will then be possible to perform blocking operations without blocking the platform thread upon which the virtual thread is mounted. == Configuring gRPC services to use virtual threads @@ -49,22 +49,22 @@ First, make sure to have the gRPC extension dependency in your build file: implementation("io.quarkus:quarkus-grpc") ---- -You also need to make sure that you are using Java 19 or later, this can be enforced in your `pom.xml` file with the following: +You also need to make sure that you are using Java 19 or later (we recommend 21+), this can be enforced in your `pom.xml` file with the following: [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] .pom.xml ---- - 19 - 19 + 21 + 21 ---- -Virtual threads are still a preview feature, so you need to start your application with the `--enable-preview` flag: +Run your application with: [source, bash] ---- -java --enable-preview -jar target/quarkus-app/quarkus-run.jar +java -jar target/quarkus-app/quarkus-run.jar ---- or to use the Quarkus Dev mode, insert the following to the `quarkus-maven-plugin` configuration: @@ -86,17 +86,12 @@ or to use the Quarkus Dev mode, insert the following to the `quarkus-maven-plugi - 19 - 19 - - --enable-preview - + 21 + 21 ---- -NOTE: The `--enable-preview` flag is not necessary with Java 21+. - Then you can start using the annotation `@RunOnVirtualThread` in your service implementation: [source, java] diff --git a/docs/src/main/asciidoc/messaging-virtual-threads.adoc b/docs/src/main/asciidoc/messaging-virtual-threads.adoc index 2612dcb74220fc..0e45e064e41cd8 100644 --- a/docs/src/main/asciidoc/messaging-virtual-threads.adoc +++ b/docs/src/main/asciidoc/messaging-virtual-threads.adoc @@ -34,7 +34,7 @@ The idea behind Quarkus Virtual Thread support for Reactive Messaging is to offl instead of running it on an event-loop thread or a worker thread. To enable virtual thread support on a message consumer method, simply add the link:{runonvthread}[@RunOnVirtualThread] annotation to the method. -If the JDK is compatible (Java 19 or later versions) then each incoming message will be offloaded to a new virtual thread. +If the JDK is compatible (Java 19 or later versions, we recommend 21+) then each incoming message will be offloaded to a new virtual thread. It will then be possible to perform blocking operations without blocking the platform thread upon which the virtual thread is mounted. == Example using the Reactive Messaging Kafka extension @@ -57,22 +57,22 @@ First, make sure to have a reactive messaging extension dependency to your build implementation("io.quarkus:quarkus-smallrye-reactive-messaging-kafka") ---- -You also need to make sure that you are using Java 19 or later, this can be enforced in your `pom.xml` file with the following: +You also need to make sure that you are using Java 19 or later (we recommend 21+), this can be enforced in your `pom.xml` file with the following: [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] .pom.xml ---- - 20 - 20 + 21 + 21 ---- -Virtual threads are still a preview feature, so you need to start your application with the `--enable-preview` flag: +Run the application with: [source, bash] ---- -java --enable-preview -jar target/quarkus-app/quarkus-run.jar +java -jar target/quarkus-app/quarkus-run.jar ---- or to use the Quarkus Dev mode, insert the following to the `quarkus-maven-plugin` configuration: @@ -80,18 +80,7 @@ or to use the Quarkus Dev mode, insert the following to the `quarkus-maven-plugi [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] .pom.xml ---- -20 - - - maven-compiler-plugin - ${compiler-plugin.version} - - - -parameters - --enable-preview - - - +21 ---- Then you can start using the annotation `@RunOnVirtualThread` on your consumer methods also annotated with `@Incoming`. diff --git a/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc b/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc index 0230546877a836..80df9473fe0746 100644 --- a/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc +++ b/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc @@ -73,26 +73,10 @@ We need to customize the `pom.xml` file to use virtual threads. [source, xml] ---- - 20 + 21 ---- -2) In the maven-compiler-plugin configuration, add the `--enable-preview` arg (only if you use Java 19 or Java 20) - -[source, xml] ----- - - maven-compiler-plugin - ${compiler-plugin.version} - - - -parameters - --enable-preview - - - ----- - -3) In the maven-surefire-plugin and maven-failsafe-plugin configurations, add the following `argLine` parameter: +2) In the maven-surefire-plugin and maven-failsafe-plugin configurations, add the following `argLine` parameter: [source, xml] ---- @@ -104,7 +88,7 @@ We need to customize the `pom.xml` file to use virtual threads. org.jboss.logmanager.LogManager ${maven.home} - --enable-preview -Djdk.tracePinnedThreads + -Djdk.tracePinnedThreads @@ -122,7 +106,7 @@ We need to customize the `pom.xml` file to use virtual threads. org.jboss.logmanager.LogManager ${maven.home} - --enable-preview -Djdk.tracePinnedThreads + -Djdk.tracePinnedThreads @@ -133,9 +117,10 @@ We need to customize the `pom.xml` file to use virtual threads. The `-Djdk.tracePinnedThreads` will detect pinned carrier threads while running tests (See xref:./virtual-threads.adoc#pinning[the virtual thread reference guide for details]). [IMPORTANT] -.--enable-preview and Java 21 +.--enable-preview on Java 19 and 20 ==== -The `--enable-preview` flag is only required if you use Java 19 or 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 @@ -202,7 +187,7 @@ public class TheBestPlaceToBeResource { @RestClient WeatherService service; @GET - @RunOnVirtualThread <1> + @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(); @@ -227,13 +212,13 @@ Make sure that you use OpenJDK and JVM versions supporting virtual thread and la [source, shell] ---- > java --version -openjdk 20.0.1 2023-04-18 <1> -OpenJDK Runtime Environment Temurin-20.0.1+9 (build 20.0.1+9) -OpenJDK 64-Bit Server VM Temurin-20.0.1+9 (build 20.0.1+9, mixed mode) +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+ +<1> Must be 19+, we recommend 21+ <2> Launch the dev mode Then, in a browser, open http://localhost:8080. @@ -262,7 +247,7 @@ In the `pom.xml,` we added an `argLine` argument to the surefire and failsafe pl [source, xml] ---- ---enable-preview -Djdk.tracePinnedThreads +-Djdk.tracePinnedThreads ---- The `-Djdk.tracePinnedThreads` dumps the stack trace if a virtual thread cannot be _unmounted_ smoothly (meaning that it blocks the carrier thread). diff --git a/docs/src/main/asciidoc/virtual-threads.adoc b/docs/src/main/asciidoc/virtual-threads.adoc index 12f931d4f8a2fc..aea9a80b91b414 100644 --- a/docs/src/main/asciidoc/virtual-threads.adoc +++ b/docs/src/main/asciidoc/virtual-threads.adoc @@ -321,22 +321,23 @@ If would not fail the tests, but at least dump start traces if the code pins the org.jboss.logmanager.LogManager ${maven.home} - --enable-preview -Djdk.tracePinnedThreads + -Djdk.tracePinnedThreads ---- -NOTE: The `--enable-preview` flag is not necessary with Java 21. +TIP: Add the `--enable-preview` in `argLine` if you are not using Java 21+. == Run application using virtual threads -Prior to Java 21, virtual threads are still an experimental feature, you need to start your application with the `--enable-preview` flag: [source, bash] ---- -java --enable-preview -jar target/quarkus-app/quarkus-run.jar +java -jar target/quarkus-app/quarkus-run.jar ---- +TIP: Prior to Java 21, virtual threads were still an experimental feature, you need to start your application with the `--enable-preview` flag. + == Build containers for application using virtual threads When running your application in JVM mode (so not compiled into native, for native check xref:native[the dedicated section]), you can follow the xref:./container-image.adoc[containerization guide] to build a container. @@ -351,13 +352,11 @@ To containerize your Quarkus application that use `@RunOnVirtualThread`, add the quarkus.container-image.build=true quarkus.container-image.group= quarkus.container-image.name= -quarkus.jib.base-jvm-image=eclipse-temurin:20.0.1_9-jre-ubi9-minimal <1> +quarkus.jib.base-jvm-image=eclipse-temurin:21-ubi9-minimal <1> quarkus.jib.platforms=linux/amd64,linux/arm64 <2> -quarkus.jib.jvm-arguments=--enable-preview <3> ---- -<1> Make sure you use a base image supporting virtual threads. Here we use an image providing Java 20. +<1> Make sure you use a base image supporting virtual threads. Here we use an image providing Java 21. <2> Select the target architecture. You can select more than one to build multi-archs images. -<3> Don't forget to use the `--enable-preview` flag if you are not using Java 21+. Then, build your container as you would do usually. For example, if you are using Maven, run: