From 153f5dfae8827259e58cca2d695c1000bcb3890e Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Mon, 21 Aug 2023 15:17:14 +0200 Subject: [PATCH] Fixes #10350 - Support Java 21 virtual threads * Introduced module `threadpool-virtual` for Java 21. * Updated virtual threads documentation to refer to Java 21. * Updated requirements that the releases should use Java 21, so that the documentation can properly render the virtual threads documentation. Signed-off-by: Simone Bordet --- .github/ISSUE_TEMPLATE/release-template.md | 9 ++-- documentation/jetty-documentation/pom.xml | 4 +- .../module-threadpool-virtual-preview.adoc | 7 ++- .../modules/module-threadpool-virtual.adoc | 36 ++++++++++++++++ .../modules/module-threadpool.adoc | 7 ++- .../modules/modules-standard.adoc | 1 + .../server/server-threadpool.adoc | 16 ++++--- .../programming-guide/arch-threads.adoc | 6 +-- .../config/etc/jetty-threadpool-virtual.xml | 43 +++++++++++++++++++ .../modules/threadpool-virtual-preview.mod | 2 +- .../config/modules/threadpool-virtual.mod | 41 ++++++++++++++++++ .../src/main/config/modules/threadpool.mod | 2 +- pom.xml | 4 +- .../tests/distribution/DistributionTests.java | 31 ++++++++++++- tests/test-http-client-transport/pom.xml | 2 +- 15 files changed, 184 insertions(+), 27 deletions(-) create mode 100644 documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual.adoc create mode 100644 jetty-server/src/main/config/etc/jetty-threadpool-virtual.xml create mode 100644 jetty-server/src/main/config/modules/threadpool-virtual.mod diff --git a/.github/ISSUE_TEMPLATE/release-template.md b/.github/ISSUE_TEMPLATE/release-template.md index 29e0a76e164..f445ee4fa40 100644 --- a/.github/ISSUE_TEMPLATE/release-template.md +++ b/.github/ISSUE_TEMPLATE/release-template.md @@ -32,14 +32,11 @@ This release process will produce releases: + [ ] Create and use branches `release/` to perform version specific release work from. + [ ] Ensure `VERSION.txt` additions for each release will be meaningful, descriptive, correct text. + [ ] Stage 9.4 release with Java 11. - + [ ] Stage 10 release with Java 19. - + [ ] Stage 11 release with Java 19. + + [ ] Stage 10 release with Java 21. + + [ ] Stage 11 release with Java 21. + [ ] Push release branches `release/` to to https://github.com/eclipse/jetty.project + [ ] Push release tags `jetty-` to https://github.com/eclipse/jetty.project + [ ] Edit a draft release (for each Jetty release) in GitHub (https://github.com/eclipse/jetty.project/releases). Content is generated with the "changelog tool". - Be mindful of the order you create multiple release drafts. The first one created will be the "oldest" when published. (eg: Draft is 9, then 10, then 11) - The last created "draft" will show up as "latest" in the github UI. - If you have to reroll, you'll have to delete the drafts and recreate them (especially so if 9 w/timestamp is in the mix of releases being worked on) - [ ] Assign issue to "test manager", who will oversee the testing of the staged releases. + [ ] Test [CometD](https://github.com/cometd/cometd). + [ ] Test [Reactive HttpClient](https://github.com/jetty-project/jetty-reactive-httpclient). @@ -58,7 +55,7 @@ This release process will produce releases: - [ ] Update Jetty versions on the website ( follow instructions in [jetty-website](https://github.com/eclipse/jetty-website/blob/master/README.md) ). + [ ] Update (or check) [Download](https://eclipse.dev/jetty/download.php) page is updated. + [ ] Update (or check) documentation page(s) are updated. -- [ ] Publish GitHub Releases in the order of oldest (eg: 9) to newest (eg: 11) (to ensure that "latest" in github is truly the latest) +- [ ] Publish GitHub Releases. - [ ] Prepare release announcement for mailing lists. - [ ] Publish any [security advisories](https://github.com/eclipse/jetty.project/security/advisories). + [ ] Edit `VERSION.txt` to include any actual CVE number next to correspondent issue. diff --git a/documentation/jetty-documentation/pom.xml b/documentation/jetty-documentation/pom.xml index cfb38991b1d..d292b87b42c 100644 --- a/documentation/jetty-documentation/pom.xml +++ b/documentation/jetty-documentation/pom.xml @@ -23,8 +23,8 @@ false - [19,) - [ERROR] OLD JDK [${java.version}] in use. Jetty documentation ${project.version} MUST use JDK 19 or newer + [21,) + [ERROR] OLD JDK [${java.version}] in use. Jetty documentation ${project.version} MUST use JDK 21 or newer diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual-preview.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual-preview.adoc index cb27aa09aba..33230257b6b 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual-preview.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual-preview.adoc @@ -14,7 +14,10 @@ [[og-module-threadpool-virtual-preview]] ===== Module `threadpool-virtual-preview` -The `threadpool-virtual-preview` module allows you to configure the server-wide thread pool, similarly to what you can do with the xref:og-module-threadpool[`threadpool`] Jetty module, but also specify to use virtual threads, introduced as a preview feature in Java 19. +The `threadpool-virtual-preview` module allows you to configure the server-wide thread pool, similarly to what you can do with the xref:og-module-threadpool[`threadpool`] Jetty module, but also specify to use virtual threads, introduced as a preview feature in Java 19 and in Java 20. + +CAUTION: Only use this module if you are using Java 19 or Java 20. +If you are using Java 21 or later, use the xref:og-module-threadpool-virtual[`threadpool-virtual`] Jetty module instead. NOTE: To enable preview features, this module needs to specify the `+--enable-preview+` command line option using the xref:og-modules-directive-exec[[exec\] directive], and as such it will fork another JVM. @@ -34,5 +37,5 @@ The name prefix to use for the virtual thread names. `jetty.threadPool.virtual.allowSetThreadLocals`:: Whether virtual threads are allowed to set thread locals. -`jetty.threadPool.useVirtualThreads`:: +`jetty.threadPool.virtual.inheritInheritableThreadLocals`:: Whether virtual threads inherit the values of `InheritableThreadLocal` variables. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual.adoc new file mode 100644 index 00000000000..e12fdef5e21 --- /dev/null +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool-virtual.adoc @@ -0,0 +1,36 @@ +// +// ======================================================================== +// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License v. 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-module-threadpool-virtual]] +===== Module `threadpool-virtual` + +The `threadpool-virtual` module allows you to configure the server-wide thread pool, similarly to what you can do with the xref:og-module-threadpool[`threadpool`] Jetty module, but also specify to use virtual threads, introduced as an official feature since Java 21. + +CAUTION: Only use this module if you are using Java 21 or later. +If you are using Java 19 or Java 20, use the xref:og-module-threadpool-virtual-preview[`threadpool-virtual-preview`] Jetty module instead. + +Refer to the xref:og-module-threadpool[`threadpool`] Jetty module for the general features provided by that Jetty module that also this Jetty module provides. + +The module properties to configure the thread pool are: + +---- +include::{JETTY_HOME}/modules/threadpool-virtual.mod[tags=documentation] +---- + +The specific properties to configure virtual threads are: + +`jetty.threadPool.virtual.namePrefix`:: +The name prefix to use for the virtual thread names. + +`jetty.threadPool.virtual.inheritInheritableThreadLocals`:: +Whether virtual threads inherit the values of `InheritableThreadLocal` variables. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc index 58a90ccd0ad..63b3b142227 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc @@ -41,4 +41,9 @@ The time, in milliseconds, after which an idle thread is released from the pool `jetty.threadPool.maxThreads`:: The max number of threads pooled by the thread pool -- defaults to 200. -If you want to use virtual threads, introduced as a preview feature in Java 19, use the xref:og-module-threadpool-virtual-preview[`threadpool-virtual-preview`] Jetty module instead (see also the xref:og-server-threadpool[section about configuring the thread pool]). +If you want to use virtual threads, introduced as a preview feature in Java 19 and Java 20, and become an official feature since Java 21, use the following modules: + +* The xref:og-module-threadpool-virtual[`threadpool-virtual`] Jetty module for Java 21 or later. +* The xref:og-module-threadpool-virtual-preview[`threadpool-virtual-preview`] Jetty module for Java 19 and Java 20. + +See also the xref:og-server-threadpool[section about configuring the thread pool]. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc index d57027506a9..e4da39d3500 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc @@ -31,5 +31,6 @@ include::module-ssl.adoc[] include::module-ssl-reload.adoc[] include::module-test-keystore.adoc[] include::module-threadpool.adoc[] +include::module-threadpool-virtual.adoc[] include::module-threadpool-virtual-preview.adoc[] include::module-well-known.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/server/server-threadpool.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/server/server-threadpool.adoc index 140a220ec78..216d2a37bfc 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/server/server-threadpool.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/server/server-threadpool.adoc @@ -47,16 +47,18 @@ Now you can customize the `threadpool.ini` file to explicitly configure the thre [[og-server-threadpool-virtual]] ===== Virtual Threads Support -Virtual threads have been introduced as a preview feature in Java 19. +Virtual threads have been introduced as a preview feature in Java 19 and Java 20, and have become an official feature since Java 21. -The xref:og-module-threadpool-virtual-preview[`threadpool-virtual-preview`] Jetty module provides support for virtual threads and it is mutually exclusive with the `threadpool` Jetty module. +The xref:og-module-threadpool-virtual-preview[`threadpool-virtual-preview`] Jetty module provides support for virtual threads in Java 19 and Java 20, and it is mutually exclusive with the `threadpool` Jetty module. + +The xref:og-module-threadpool-virtual[`threadpool-virtual`] Jetty module provides support for virtual threads in Java 21 or later, and it is mutually exclusive with the `threadpool` Jetty module. If you have already enabled the `threadpool` Jetty module, it is sufficient to remove it by removing the `$JETTY_BASE/start.d/threadpool.ini` file. -Then, you can enable the xref:og-module-threadpool-virtual-preview[`threadpool-virtual-preview`] module: +When using Java 21 or later, you can enable the xref:og-module-threadpool-virtual[`threadpool-virtual`] module: ---- -$ java -jar $JETTY_HOME/start.jar --add-modules=threadpool-virtual-preview,http +$ java -jar $JETTY_HOME/start.jar --add-modules=threadpool-virtual,http ---- After the command above, the `$JETTY_BASE` directory looks like this: @@ -68,12 +70,12 @@ $JETTY_BASE │ └── jetty-logging.properties └── start.d ├── http.ini - └── threadpool-virtual-preview.ini + └── threadpool-virtual.ini ---- -Now you can customize the `threadpool-virtual-preview.ini` file to explicitly configure the thread pool and the virtual threads and then start Jetty: +Now you can customize the `threadpool-virtual.ini` file to explicitly configure the thread pool and the virtual threads and then start Jetty: [source,subs=quotes,options=nowrap] ---- -include::jetty[setupArgs="--add-modules=threadpool-virtual-preview,http"] +include::jetty[setupArgs="--add-modules=threadpool-virtual,http"] ---- diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-threads.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-threads.adoc index f39c7133c72..a2accfc04eb 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-threads.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-threads.adoc @@ -176,7 +176,7 @@ Jetty's xref:pg-arch-threads[threading architecture] requires a more sophisticat Jetty's default thread pool implementation is link:{javadoc-url}/org/eclipse/jetty/util/thread/QueuedThreadPool.html[`QueuedThreadPool`]. -`QueuedThreadPool` integrates with the xref:pg-arch-bean[Jetty component model], implements `Executor`, provides a `TryExecutor` implementation (discussed in the xref:pg-arch-threads-execution-strategy-adaptive[adaptive execution strategy section]), and supports xref:pg-arch-threads-thread-pool-virtual-threads[virtual threads] (introduced as a preview feature in Java 19). +`QueuedThreadPool` integrates with the xref:pg-arch-bean[Jetty component model], implements `Executor`, provides a `TryExecutor` implementation (discussed in the xref:pg-arch-threads-execution-strategy-adaptive[adaptive execution strategy section]), and supports xref:pg-arch-threads-thread-pool-virtual-threads[virtual threads] (introduced as a preview feature in Java 19 and Java 20, and as an official feature since Java 21). `QueuedThreadPool` can be configured with a `maxThreads` value. @@ -203,9 +203,9 @@ A good balance between `QueuedThreadPool.idleTimeout` and `QueuedThreadPool.maxE [[pg-arch-threads-thread-pool-virtual-threads]] ===== Virtual Threads -Virtual threads have been introduced in Java 19 as a preview feature. +Virtual threads have been introduced in Java 19 and Java 20 as a preview feature, and have become an official feature since Java 21. -NOTE: In Java versions where virtual threads are a preview feature, remember to add `+--enable-preview+` to the command line options to use virtual threads. +NOTE: In Java versions where virtual threads are a preview feature, remember to add `+--enable-preview+` to the JVM command line options to use virtual threads. `QueuedThreadPool` can be configured to use virtual threads by specifying the virtual threads `Executor`: diff --git a/jetty-server/src/main/config/etc/jetty-threadpool-virtual.xml b/jetty-server/src/main/config/etc/jetty-threadpool-virtual.xml new file mode 100644 index 00000000000..71dc9444ba8 --- /dev/null +++ b/jetty-server/src/main/config/etc/jetty-threadpool-virtual.xml @@ -0,0 +1,43 @@ + + + + + + + + + + + + + + + + + + -virtual- + + + 0 + + + + + + + + + + + + + + + + + org.eclipse.jetty + + Virtual threads are enabled. + + + diff --git a/jetty-server/src/main/config/modules/threadpool-virtual-preview.mod b/jetty-server/src/main/config/modules/threadpool-virtual-preview.mod index 05ee57659f1..68afe360c40 100644 --- a/jetty-server/src/main/config/modules/threadpool-virtual-preview.mod +++ b/jetty-server/src/main/config/modules/threadpool-virtual-preview.mod @@ -1,5 +1,5 @@ [description] -Enables and configures the Server ThreadPool with support for virtual threads. +Enables and configures the Server ThreadPool with support for virtual threads in Java 19 and Java 20. [exec] --enable-preview diff --git a/jetty-server/src/main/config/modules/threadpool-virtual.mod b/jetty-server/src/main/config/modules/threadpool-virtual.mod new file mode 100644 index 00000000000..54a2912b4f1 --- /dev/null +++ b/jetty-server/src/main/config/modules/threadpool-virtual.mod @@ -0,0 +1,41 @@ +[description] +Enables and configures the Server ThreadPool with support for virtual threads in Java 21 or later. + +[depends] +logging + +[provides] +threadpool + +[xml] +etc/jetty-threadpool-virtual.xml + +[ini-template] +# tag::documentation[] +## Platform threads name prefix. +#jetty.threadPool.namePrefix=qtp + +## Minimum number of pooled threads. +#jetty.threadPool.minThreads=10 + +## Maximum number of pooled threads. +#jetty.threadPool.maxThreads=200 + +## Number of reserved threads (-1 for heuristic). +#jetty.threadPool.reservedThreads=-1 + +## Thread idle timeout (in milliseconds). +#jetty.threadPool.idleTimeout=60000 + +## The max number of idle threads that can be evicted in one idleTimeout period. +#jetty.threadPool.maxEvictCount=1 + +## Whether to output a detailed dump. +#jetty.threadPool.detailedDump=false + +## Virtual threads name prefix. +#jetty.threadPool.virtual.namePrefix=qtp-virtual- + +## Whether virtual threads inherits the values of inheritable thread locals. +#jetty.threadPool.virtual.inheritInheritableThreadLocals=true +# end::documentation[] diff --git a/jetty-server/src/main/config/modules/threadpool.mod b/jetty-server/src/main/config/modules/threadpool.mod index 784c0449fee..0efb939dc3e 100644 --- a/jetty-server/src/main/config/modules/threadpool.mod +++ b/jetty-server/src/main/config/modules/threadpool.mod @@ -25,7 +25,7 @@ etc/jetty-threadpool.xml #jetty.threadPool.reservedThreads=-1 ## Whether to use virtual threads, if the runtime supports them. -## Deprecated, use Jetty module 'threadpool-virtual-preview' instead. +## Deprecated, use Jetty module 'threadpool-virtual' instead. #jetty.threadPool.useVirtualThreads=false ## Thread idle timeout (in milliseconds). diff --git a/pom.xml b/pom.xml index 28ff2e7b631..d2133d1706c 100644 --- a/pom.xml +++ b/pom.xml @@ -2216,8 +2216,8 @@ - [19,) - [ERROR] OLD JDK [${java.version}] in use. Jetty Release ${project.version} MUST use JDK 19 or newer + [21,) + [ERROR] OLD JDK [${java.version}] in use. Jetty Release ${project.version} MUST use JDK 21 or newer diff --git a/tests/test-distribution/src/test/java/org/eclipse/jetty/tests/distribution/DistributionTests.java b/tests/test-distribution/src/test/java/org/eclipse/jetty/tests/distribution/DistributionTests.java index 00d5e8c5cbe..e1f6feddea0 100644 --- a/tests/test-distribution/src/test/java/org/eclipse/jetty/tests/distribution/DistributionTests.java +++ b/tests/test-distribution/src/test/java/org/eclipse/jetty/tests/distribution/DistributionTests.java @@ -1321,7 +1321,7 @@ public class DistributionTests extends AbstractJettyHomeTest @Test @DisabledForJreRange(max = JRE.JAVA_18) - public void testVirtualThreadPool() throws Exception + public void testVirtualThreadPoolPreview() throws Exception { String jettyVersion = System.getProperty("jettyVersion"); JettyHomeTester distribution = JettyHomeTester.Builder.newInstance() @@ -1347,4 +1347,33 @@ public class DistributionTests extends AbstractJettyHomeTest } } } + + @Test + @DisabledForJreRange(max = JRE.JAVA_20) + public void testVirtualThreadPool() throws Exception + { + String jettyVersion = System.getProperty("jettyVersion"); + JettyHomeTester distribution = JettyHomeTester.Builder.newInstance() + .jettyVersion(jettyVersion) + .mavenLocalRepository(System.getProperty("mavenRepoPath")) + .build(); + + try (JettyHomeTester.Run run1 = distribution.start("--add-modules=threadpool-virtual,http")) + { + assertTrue(run1.awaitFor(10, TimeUnit.SECONDS)); + assertEquals(0, run1.getExitValue()); + + int httpPort = distribution.freePort(); + try (JettyHomeTester.Run run2 = distribution.start(List.of("jetty.http.selectors=1", "jetty.http.port=" + httpPort))) + { + assertTrue(run2.awaitConsoleLogsFor("Started Server@", 10, TimeUnit.SECONDS)); + + startHttpClient(); + ContentResponse response = client.newRequest("localhost", httpPort) + .timeout(15, TimeUnit.SECONDS) + .send(); + assertEquals(HttpStatus.NOT_FOUND_404, response.getStatus()); + } + } + } } diff --git a/tests/test-http-client-transport/pom.xml b/tests/test-http-client-transport/pom.xml index 13dbb5af557..1f44bb158ef 100644 --- a/tests/test-http-client-transport/pom.xml +++ b/tests/test-http-client-transport/pom.xml @@ -58,7 +58,7 @@ enable-foreign-and-virtual-threads-preview - [19,) + [19,21)