Add new GC mode JEP318

A new suboption -Xgcpolicy:nogc. A new -XX option: -XXUseNoGC Add TOC entry for XX topic Closes: eclipse-openj9#30 Signed-off-by: Sue Chaplain <[email protected]>
SueChaplain · Jun 5, 2018 · d3f3985 · d3f3985
1 parent 37811d1
commit d3f3985
Show file tree

Hide file tree

Showing 3 changed files with 120 additions and 55 deletions.
diff --git a/docs/xgcpolicy.md b/docs/xgcpolicy.md
@@ -25,21 +25,25 @@
 # -Xgcpolicy
 
 
-Controls the behavior of the garbage collector.
+Controls the behavior of the garbage collector by specifying different garbage collection policies.
 
 ## Syntax
 
         -Xgcpolicy:<parameter>
 
 ## Parameters
 
-Specify the garbage collection policy that you want the OpenJ9 VM to use:
-
-### `gencon`
+| Parameter                                                        | Default  |
+|------------------------------------------------------------------|----------|
+| [`balanced`](#balanced)                                          |          |
+| [`gencon`](#gencon)                                              | <i class="fa fa-check" aria-hidden="true"></i><span class="sr-only">Default</span> |
+| [`metronome`](#metronome) (AIX<sup>&reg;</sup>, Linux x86 only)  |          |
+| [`optavgpause`](#optavdpause)                                    |          |
+| [`optthruput`](#optthruput)                                      |          |
+| [`subpool`](#subpool) (AIX, Linux, z/OS<sup>&reg;</sup> only)    |          |
 
-        -Xgcpolicy:gencon
 
-: The generational concurrent policy (default) uses a concurrent mark phase combined with generational garbage collection to help minimize the time that is spent in any garbage collection pause. This policy is particularly useful for applications with many short-lived objects, such as transactional applications. Pause times can be significantly shorter than with the `optthruput` policy, while still producing good throughput. Heap fragmentation is also reduced.
+Specify the garbage collection policy that you want the OpenJ9 VM to use:
 
 ### `balanced`
 
@@ -57,33 +61,33 @@ The initial heap size is *Xmx/1024*, rounded down to the nearest power of 2, whe
 
 The following options can also be specified on the command line with `-Xgcpolicy:balanced`:
 
-- -Xalwaysclassgc
-- -Xclassgc
-- -Xcompactexplicitgc
-- -Xdisableexcessivegc
-- -Xdisableexplicitgc
-- -Xenableexcessivegc
-- -Xgcthreads<number>
-- -Xgcworkpackets<number>
-- -Xmaxe<size>
-- -Xmaxf<percentage>
-- -Xmaxt<percentage>
-- -Xmca<size>
-- -Xmco<size>
-- -Xmine<size>
-- -Xminf<percentage>
-- -Xmint<percentage>
-- -Xmn<size>
-- -Xmns<size>
-- -Xmnx<size>
-- -Xms<size>
-- -Xmx<size>
-- -Xnoclassgc
-- -Xnocompactexplicitgc
-- -Xnuma:none
-- -Xsoftmx<size>
-- -Xsoftrefthreshold<number>
-- -Xverbosegclog[:<file> [, <X>,<Y>]]
+- `-Xalwaysclassgc`
+- `-Xclassgc`
+- `-Xcompactexplicitgc`
+- `-Xdisableexcessivegc`
+- `-Xdisableexplicitgc`
+- `-Xenableexcessivegc`
+- `-Xgcthreads<number>`
+- `-Xgcworkpackets<number>`
+- `-Xmaxe<size>`
+- `-Xmaxf<percentage>`
+- `-Xmaxt<percentage>`
+- `-Xmca<size>`
+- `-Xmco<size>`
+- `-Xmine<size>`
+- `-Xminf<percentage>`
+- `-Xmint<percentage>`
+- `-Xmn<size>`
+- `-Xmns<size>`
+- `-Xmnx<size>`
+- `-Xms<size>`
+- `-Xmx<size>`
+- `-Xnoclassgc`
+- `-Xnocompactexplicitgc`
+- `-Xnuma:none`
+- `-Xsoftmx<size>`
+- `-Xsoftrefthreshold<number>`
+- `-Xverbosegclog[:<file> [, <X>,<Y>]]`
 
 The behavior of the following options is different when specified with `-Xgcpolicy:balanced`:
 
@@ -95,25 +99,30 @@ The behavior of the following options is different when specified with `-Xgcpoli
 
 The following options are ignored when specified with `-Xgcpolicy:balanced`:
 
-- -Xconcurrentbackground<number>
-- -Xconcurrentlevel<number>
-- -Xconcurrentslack<size>
-- -Xconmeter:<soa | loa | dynamic>
-- -Xdisablestringconstantgc
-- -Xenablestringconstantgc
-- -Xloa
-- -Xloainitial<percentage>
-- -Xloamaximum<percentage>
-- -Xloaminimum<percentage>
-- -Xmo<size>
-- -Xmoi<size>
-- -Xmos<size>
-- -Xmr<size>
-- -Xmrx<size>
-- -Xnoloa
-- -Xnopartialcompactgc (deprecated)
-- -Xpartialcompactgc (deprecated)
+- `-Xconcurrentbackground<number>`
+- `-Xconcurrentlevel<number>`
+- `-Xconcurrentslack<size>`
+- `-Xconmeter:<soa | loa | dynamic>`
+- `-Xdisablestringconstantgc`
+- `-Xenablestringconstantgc`
+- `-Xloa`
+- `-Xloainitial<percentage>`
+- `-Xloamaximum<percentage>`
+- `-Xloaminimum<percentage>`
+- `-Xmo<size>`
+- `-Xmoi<size>`
+- `-Xmos<size>`
+- `-Xmr<size>`
+- `-Xmrx<size>`
+- `-Xnoloa`
+- `-Xnopartialcompactgc` (deprecated)
+- `-Xpartialcompactgc` (deprecated)
 
+### `gencon`
+
+        -Xgcpolicy:gencon
+
+: The generational concurrent policy (default) uses a concurrent mark phase combined with generational garbage collection to help minimize the time that is spent in any garbage collection pause. This policy is particularly useful for applications with many short-lived objects, such as transactional applications. Pause times can be significantly shorter than with the `optthruput` policy, while still producing good throughput. Heap fragmentation is also reduced.
 
 ### `metronome` (AIX<sup>&reg;</sup>, Linux<sup>&trade;</sup> only)
 
@@ -154,24 +163,32 @@ java -Xgcpolicy:metronome -Xmx30m -Xgc:targetUtilization=75 Test
 `-Xmx<size>`
 : Specifies the Java heap size. Unlike other garbage collection strategies, the real-time Metronome GC does not support heap expansion. There is not an initial or maximum heap size option. You can specify only the maximum heap size.
 
+### `nogc`
+
+        -Xgcpolicy:nogc
+
+: When this policy is enabled, the Java object heap is expanded in the normal way until the limit is reached, but memory is not reclaimed through garbage collection. This policy can be useful for test
+purposes and for short-lived applications. When the limit is reached an `OutOfMemory` error is generated and the VM shuts down. This policy can also be enabled with the [`-XX:+UseNoGC`](#xxusenogc.md) option.
 
 ### `optavgpause`
 
         -Xgcpolicy:optavgpause
 
 : The "optimize for pause time" policy uses concurrent mark and concurrent sweep phases. Pause times are shorter than with `optthruput`, but application throughput is reduced because some garbage collection work is taking place while the application is running. Consider using this policy if you have a large heap size (available on 64-bit platforms), because this policy limits the effect of increasing heap size on the length of the garbage collection pause. However, if your application uses many short-lived objects, the `gencon` policy might produce better performance.
 
+### `optthruput`
+
+        -Xgcpolicy:optthruput
+
+: The "optimize for throughput" policy disables the concurrent mark phase. The application stops during global garbage collection, so long pauses can occur. This configuration is typically used for large-heap applications when high application throughput, rather than short garbage collection pauses, is the main performance goal. If your application cannot tolerate long garbage collection pauses, consider using another policy, such as `gencon`.
+
 ### `subpool`  (AIX, Linux, and z/OS<sup>&reg;</sup> only)
 
         -Xgcpolicy:subpool
 
 : The subpool policy is deprecated and is now an alias for `optthruput`. Therefore, if you use this option, the effect is the same as `optthruput`.
 
-### `optthruput`
 
-        -Xgcpolicy:optthruput
-
-: The "optimize for throughput" policy disables the concurrent mark phase. The application stops during global garbage collection, so long pauses can occur. This configuration is typically used for large-heap applications when high application throughput, rather than short garbage collection pauses, is the main performance goal. If your application cannot tolerate long garbage collection pauses, consider using another policy, such as `gencon`.
 
 
 

diff --git a/docs/xxusenogc.md b/docs/xxusenogc.md
@@ -0,0 +1,47 @@
+<!--
+* Copyright (c) 2017, 2018 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 WITH
+* Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
+-->
+
+# -XX:\[+|-\]UseNoGC  
+
+The `-XX:+UseNoGC` option enables a garbage collection policy that expands the Java object heap in the normal way until the limit is reached, but memory is not
+reclaimed through garbage collection.
+
+## Syntax
+
+        -XX:[+|-]UseNoGC
+
+| Setting                 | Effect | Default                                                                            |
+|-------------------------|--------|:----------------------------------------------------------------------------------:|
+|`-XX:+UseNoGC`           | Enable |                                                                                    |
+|`-XX:-UseNoGC`           | Disable| <i class="fa fa-check" aria-hidden="true"></i><span class="sr-only">Default</span> |
+
+## Explanation
+
+This policy can be useful for test purposes and for short-lived applications. When the limit is reached an `OutOfMemory` error is generated and the VM shuts down. This policy can also be enabled with the [`-Xgcpolicy:nogc`](#xgcpolicy.md) option.
+
+The `-XX:-UseNoGC` option turns off a previously enabled `-XX:+UseNoGC` option.
+
+
+
+<!-- ==== END OF TOPIC ==== xxusenogc.md ==== -->
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -274,6 +274,7 @@ pages:
             - "-XX:SharedCacheHardLimit"                                         : xxsharedcachehardlimit.md
             - "-XX:-StackTraceInThrowable"                                       : xxstacktraceinthrowable.md
             - "-XX:[+|-]UseCompressedOops"                                       : xxusecompressedoops.md
+            - "-XX:[+|-]UseNoGC"                                                 : xxusenogc.md
             - "-XX:[+|-]VerboseVerification"                                     : xxverboseverification.md
             - "-XX:[+|-]VMLockClassLoader"                                       : xxvmlockclassloader.md