Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify virtual threads guide by pushing users to 21 #36413

Merged
merged 1 commit into from
Oct 11, 2023
Merged

Simplify virtual threads guide by pushing users to 21 #36413

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 8 additions & 31 deletions docs/src/main/asciidoc/virtual-threads.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ include::_attributes.adoc[]
:topics: virtual-threads
:extensions: io.quarkus:quarkus-core

This guide explains how to benefit from Java 19+ virtual threads in Quarkus application.
This guide explains how to benefit from Java 21+ virtual threads in Quarkus application.

== What are virtual threads?

Expand All @@ -40,7 +40,8 @@ It isn't a class distinct from link:{Thread}[Thread] or `VirtualThread` but rath
=== Differences between virtual threads and platform threads
We will give a brief overview of the topic here; please refer to the link:{vthreadjep}[JEP 425] for more information.

Virtual threads are a feature available since Java 19, aiming at providing a cheap alternative to platform threads for I/O-bound workloads.
Virtual threads are a feature available since Java 19 (Java 21 is the first LTS version including virtual threads),
aiming at providing a cheap alternative to platform threads for I/O-bound workloads.

Until now, platform threads were the concurrency unit of the JVM.
They are a wrapper over OS structures.
Expand Down Expand Up @@ -165,7 +166,7 @@ Quarkus handles the creation of the virtual thread and the offloading.
Since virtual threads are disposable entities, the fundamental idea of `@RunOnVirtualThread` is to offload the execution of an endpoint handler on a new virtual thread instead of running it on an event-loop or worker thread (in the case of RESTEasy Reactive).

To do so, it suffices to add the link:{runonvthread}[@RunOnVirtualThread] annotation to the endpoint.
If the Java Virtual Machine used to **run** the application provides virtual thread support (so, Java 19 or later versions), then the endpoint execution is offloaded to a virtual thread.
If the Java Virtual Machine used to **run** the application provides virtual thread support (so Java 21 or later versions), then the endpoint execution is offloaded to a virtual thread.
It will then be possible to perform blocking operations without blocking the platform thread upon which the virtual thread is mounted.

In the case of RESTEasy Reactive, this annotation can only be used on endpoints annotated with link:{blockingannotation}[@Blocking] or
Expand All @@ -192,34 +193,17 @@ Add the following dependency to your build file:
implementation("io.quarkus:quarkus-resteasy-reactive")
----

Then, you also need to make sure that you are using the version 19+ of Java, this can be enforced in your pom.xml file with the following:
Then, you also need to make sure that you are using Java 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>
----

Finally, until Java 21, you need to configure your compiler plugin with the `--enable-preview` flag.
If you use Maven, make sure that the configuration of the Maven compiler plugin is the following:

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

==== Three development and execution models

The example below shows the differences between three endpoints, all of them querying a _fortune_ in the database then
Expand Down Expand Up @@ -382,14 +366,7 @@ mvn package

=== Using a local GraalVM installation

To compile a Quarkus applications leveraging `@RunOnVirtualThread` into native executable, you must be sure to use a GraalVM / Mandrel `native-image` supporting virtual threads, so providing at least Java 19+.

Then, until Java 21, you need to add the following property to your `application.properties` file:

[source, properties]
----
quarkus.native.additional-build-args=--enable-preview
----
To compile a Quarkus applications leveraging `@RunOnVirtualThread` into a native executable, you must be sure to use a GraalVM / Mandrel `native-image` supporting virtual threads, so providing at least Java 21.

Build the native executable as indicated on xref:./building-native-image.adoc[the native compilation guide].
For example, with Maven, run:
Expand Down