Merge pull request eclipse-openj9#1165 from Sreekala-Gopakumar/1124Co…

…ntinuationCache

Documentation for -XX:ContinuationCache

docs/version0.41.md

@@ -27,6 +27,7 @@ The following new features and notable changes since version 0.40.0 are included
 
 - [New binaries and changes to supported environments](#binaries-and-supported-environments)
 - ![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) [New `-XX:[+|-]ShowCarrierFrames` option added](#new-xx-showcarrierframes-option-added) ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
+- ![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) [New `-XX:ContinuationCache` option added](#new-xxcontinuationcache-option-added) ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
 - ![Start of content that applies only to Java 11+ (LTS)](cr/java11plus.png) [`-XX:+CompactStrings` option enabled by default](#-xxcompactstrings-option-enabled-by-default) ![End of content that applies only to Java 11 and later](cr/java_close_lts.png)
 - [Change in behavior of `-Xshareclasses:readonly`](#change-in-behavior-of-xshareclassesreadonly)
 
@@ -44,6 +45,12 @@ A VM maintains multiple platform threads that are used as carrier threads to run
 
 For more information, see [`-XX:[+|-]ShowCarrierFrames`](xxshowcarrierframes.md). ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
 
+### ![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) New `-XX:ContinuationCache` option added
+
+When a virtual thread is created, it is associated with a continuation, which holds the target task of the virtual thread. The VM saves the current thread state in an internal data structure that is linked with the continuation and allocates the memory for that structure. The VM stores the internal data structure in a continuation cache. New continuations can reuse the cached structure instead of allocating new memory for it.
+
+You can optimize the virtual thread performance by tuning the continuation tier 1 and 2 cache size with the [`-XX:ContinuationCache`](xxcontinuationcache.md) option. ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
+
 ### ![Start of content that applies only to Java 11+ (LTS)](cr/java11plus.png) `-XX:+CompactStrings` option enabled by default
 
 Like HotSpot, the`-XX:+CompactStrings` option is now enabled by default on Java™ 11 and later. In the earlier versions, this option is disabled by default.

docs/xxcontinuationcache.md

@@ -0,0 +1,60 @@
+<!--
+* Copyright (c) 2017, 2022 IBM Corp. and others
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which accompanies this distribution and is available at
+* https://www.eclipse.org/legal/epl-2.0/ or the Apache
+* License, Version 2.0 which accompanies this distribution and
+* is available at https://www.apache.org/licenses/LICENSE-2.0.
+*
+* This Source Code may also be made available under the
+* following Secondary Licenses when the conditions for such
+* availability set forth in the Eclipse Public License, v. 2.0
+* are satisfied: GNU General Public License, version 2 with
+* the GNU Classpath Exception [1] and GNU General Public
+* License, version 2 with the OpenJDK Assembly Exception [2].
+*
+* [1] https://www.gnu.org/software/classpath/license.html
+* [2] http://openjdk.java.net/legal/assembly-exception.html
+*
+* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 OR GPL-2.0-only WITH OpenJDK-assembly-exception-1.0
+-->
+
+# -XX:ContinuationCache
+
+![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) This option sets the continuation tier 1 and 2 cache size to optimize virtual thread performance.
+
+## Syntax
+
+        -XX:ContinuationCache:t1=<size>,t2=<size>
+
+| Setting                 | Value      | Default                     |
+|-------------------------|------------|:---------------------------:|
+| `t1=<size>`    |  0-2^32 (4,294,967,295) |  1                       |
+| `t2=<size>`    |  0-2^32 (4,294,967,295) |  Number of processors x 2                       |
+
+Where `t1` is the tier 1 cache and `t2` is the tier 2 cache.
+
+The tier 1 cache holds data that is not shareable between threads.
+
+The tier 2 cache holds data that can be shared globally between threads.
+
+## Explanation
+
+When a virtual thread is created, it is associated with a continuation, which holds the target task of the virtual thread. When a virtual thread starts, the VM saves the current thread (carrier thread) state in an internal data structure that is linked with the continuation. When the associated continuation starts, the VM allocates the memory for the internal data structure and stores its reference in the continuation. When the continuation finishes, the VM stores the internal data structure in a cache instead of freeing the associated memory. New continuations can reuse the cached structure instead of allocating new memory for it. The VM can resume thread execution from the saved state later, typically on a different thread.
+
+If the virtual thread stops, the VM loads the state of the previous thread from the continuation and runs that thread. When the virtual thread does not complete running, the last state of the virtual thread is stored in the continuation during the stop operation. At a later point, the scheduler runs the incomplete virtual thread using the thread state stored in the continuation.
+
+Reusing the cached structure improves the performance of creating virtual threads. The performance benefits are more evident in applications that scale to millions of virtual threads.
+
+The continuation cache is implemented in two tiers, tier 1 and tier 2. You can set the maximum size for the two tiers with the `-XX:ContinuationCache` option. If an application uses more than 10000 virtual threads, setting a larger cache size might improve performance.
+
+When the size of the cache increases, the number of allocations reduces but the cache lookup time might also increase. Evaluate both the number of allocations and the optimal lookup time to set the appropriate cache size. ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
+
+## See also
+
+- [`-XX:[+|-]ShowCarrierFrames`](xxshowcarrierframes.md)
+
+
+<!-- ==== END OF TOPIC ==== xxcontinuationcache.md ==== -->

mkdocs.yml

@@ -382,6 +382,7 @@ nav:
             - "-XX:codecachetotal"                                               : xxcodecachetotal.md
             - "-XX:codecachetotalMaxRAMPercentage"                               : xxcodecachetotalmaxrampercentage.md
             - "-XX:[+|-]CompactStrings"                                          : xxcompactstrings.md
+            - "-XX:ContinuationCache"                                            : xxcontinuationcache.md
             - "-XX:DiagnoseSyncOnValueBasedClasses"                              : xxdiagnosesynconvaluebasedclasses.md
             - "-XX:[+|-]DisableExplicitGC"                                       : xxdisableexplicitgc.md
             - "-XX:[+|-]DisclaimJitScratch"                                      : xxdisclaimjitscratch.md