Skip to content

Commit

Permalink
Update virtual thread documentation to Java 21
Browse files Browse the repository at this point in the history
  • Loading branch information
@cescoffier
cescoffier committed Oct 26, 2023
1 parent 107c0c2 commit c252c58
Show file tree
Hide file tree
Showing 4 changed files with 35 additions and 67 deletions.
21 changes: 8 additions & 13 deletions docs/src/main/asciidoc/grpc-virtual-threads.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
----
<properties>
<maven.compiler.source>19</maven.compiler.source>
<maven.compiler.target>19</maven.compiler.target>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
</properties>
----

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:
Expand All @@ -86,17 +86,12 @@ or to use the Quarkus Dev mode, insert the following to the `quarkus-maven-plugi
</execution>
</executions>
<configuration>
<source>19</source>
<target>19</target>
<compilerArgs>
<arg>--enable-preview</arg>
</compilerArgs>
<source>21</source>
<target>21</target>
</configuration>
</plugin>
----

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]
Expand Down
25 changes: 7 additions & 18 deletions docs/src/main/asciidoc/messaging-virtual-threads.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -57,41 +57,30 @@ 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
----
<properties>
<maven.compiler.source>20</maven.compiler.source>
<maven.compiler.target>20</maven.compiler.target>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
</properties>
----

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:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<maven.compiler.release>20</maven.compiler.release>
<!-- ... -->
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>${compiler-plugin.version}</version>
<configuration>
<compilerArgs>
<arg>-parameters</arg>
<arg>--enable-preview</arg>
</compilerArgs>
</configuration>
</plugin>
<maven.compiler.release>21</maven.compiler.release>
----

Then you can start using the annotation `@RunOnVirtualThread` on your consumer methods also annotated with `@Incoming`.
Expand Down
41 changes: 13 additions & 28 deletions docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,26 +73,10 @@ We need to customize the `pom.xml` file to use virtual threads.

[source, xml]
----
<maven.compiler.release>20</maven.compiler.release>
<maven.compiler.release>21</maven.compiler.release>
----

2) In the maven-compiler-plugin configuration, add the `--enable-preview` arg (only if you use Java 19 or Java 20)

[source, xml]
----
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>${compiler-plugin.version}</version>
<configuration>
<compilerArgs>
<arg>-parameters</arg>
<arg>--enable-preview</arg> <!-- Added line -->
</compilerArgs>
</configuration>
</plugin>
----

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]
----
Expand All @@ -104,7 +88,7 @@ We need to customize the `pom.xml` file to use virtual threads.
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
<argLine>--enable-preview -Djdk.tracePinnedThreads</argLine> <!-- Added line -->
<argLine>-Djdk.tracePinnedThreads</argLine> <!-- Added line -->
</configuration>
</plugin>
<plugin>
Expand All @@ -122,7 +106,7 @@ We need to customize the `pom.xml` file to use virtual threads.
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
<argLine>--enable-preview -Djdk.tracePinnedThreads</argLine> <!-- Added line -->
<argLine>-Djdk.tracePinnedThreads</argLine> <!-- Added line -->
</configuration>
</execution>
</executions>
Expand All @@ -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
Expand Down Expand Up @@ -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();
Expand All @@ -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.
Expand Down Expand Up @@ -262,7 +247,7 @@ In the `pom.xml,` we added an `argLine` argument to the surefire and failsafe pl

[source, xml]
----
<argLine>--enable-preview -Djdk.tracePinnedThreads</argLine>
<argLine>-Djdk.tracePinnedThreads</argLine>
----

The `-Djdk.tracePinnedThreads` dumps the stack trace if a virtual thread cannot be _unmounted_ smoothly (meaning that it blocks the carrier thread).
Expand Down
15 changes: 7 additions & 8 deletions docs/src/main/asciidoc/virtual-threads.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -321,22 +321,23 @@ If would not fail the tests, but at least dump start traces if the code pins the
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
<argLine>--enable-preview -Djdk.tracePinnedThreads</argLine>
<argLine>-Djdk.tracePinnedThreads</argLine>
</configuration>
</plugin>
----

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.
Expand All @@ -351,13 +352,11 @@ To containerize your Quarkus application that use `@RunOnVirtualThread`, add the
quarkus.container-image.build=true
quarkus.container-image.group=<your-group-name>
quarkus.container-image.name=<you-container-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:
Expand Down

0 comments on commit c252c58

Please sign in to comment.