Stack Threads Documentation

This change adds some additional documentation pointing out that non-blocking
runtimes such as Netty require many fewer threads and that you should probably
configuration your container appropriately.

[resolves cloudfoundry#666]

Signed-off-by: Ben Hale <bhale@pivotal.io>

README.md

@@ -24,7 +24,7 @@ The following are _very_ simple examples for deploying the artifact types that w
 The buildpack default configuration can be overridden with an environment variable matching the configuration file you wish to override minus the `.yml` extension and with a prefix of `JBP_CONFIG`. It is not possible to add new configuration properties and properties with `nil` or empty values will be ignored by the buildpack (in this case you will have to extend the buildpack, see below). The value of the variable should be valid inline yaml, referred to as "flow style" in the yaml spec ([Wikipedia][] has a good description of this yaml syntax). For example, to change the default version of Java to 7 and adjust the memory heuristics apply this environment variable to the application.
 
 ```bash
-$ cf set-env my-application JBP_CONFIG_OPEN_JDK_JRE '{ jre: { version: 1.7.0_+ }, memory_calculator: { stack_threads: 200 } }'
+$ cf set-env my-application JBP_CONFIG_OPEN_JDK_JRE '{ jre: { version: 11.+ }, memory_calculator: { stack_threads: 25 } }'
 ```
 
 If the key or value contains a special character such as `:` it should be escaped with double quotes. For example, to change the default repository path for the buildpack.

docs/jre-open_jdk_jre.md

@@ -110,15 +110,14 @@ headroom: 10
 
 #### Stack Threads
 
-The amount of memory that should be allocated to stacks is given as an amount of memory per
-thread with the Java option `-Xss`. If an explicit number of
-threads should be used for the calculation of stack memory, then it should be specified as in
-the following example:
+The amount of memory that should be allocated to stacks is given as an amount of memory per thread with the Java option `-Xss`. If an explicit number of threads should be used for the calculation of stack memory, then it should be specified as in the following example:
 
 ```yaml
 stack_threads: 500
 ```
 
+Note that the default value of 250 threads is optimized for a default Tomcat configuration.  If you are using another container, especially something non-blocking like Netty, it's more appropriate to use a significantly smaller value.  Typically 25 threads would cover the needs of both the server (Netty) and the threads started by the JVM itself.
+
 #### Java Options
 
 If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to

docs/jre-oracle_jre.md

@@ -126,15 +126,14 @@ headroom: 10
 
 #### Stack Threads
 
-The amount of memory that should be allocated to stacks is given as an amount of memory per
-thread with the Java option `-Xss`. If an explicit number of
-threads should be used for the calculation of stack memory, then it should be specified as in
-the following example:
+The amount of memory that should be allocated to stacks is given as an amount of memory per thread with the Java option `-Xss`. If an explicit number of threads should be used for the calculation of stack memory, then it should be specified as in the following example:
 
 ```yaml
 stack_threads: 500
 ```
 
+Note that the default value of 250 threads is optimized for a default Tomcat configuration.  If you are using another container, especially something non-blocking like Netty, it's more appropriate to use a significantly smaller value.  Typically 25 threads would cover the needs of both the server (Netty) and the threads started by the JVM itself.
+
 #### Java Options
 
 If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to

docs/jre-sap_machine_jre.md

@@ -113,15 +113,14 @@ headroom: 10
 
 #### Stack Threads
 
-The amount of memory that should be allocated to stacks is given as an amount of memory per
-thread with the Java option `-Xss`. If an explicit number of
-threads should be used for the calculation of stack memory, then it should be specified as in
-the following example:
+The amount of memory that should be allocated to stacks is given as an amount of memory per thread with the Java option `-Xss`. If an explicit number of threads should be used for the calculation of stack memory, then it should be specified as in the following example:
 
 ```yaml
 stack_threads: 500
 ```
 
+Note that the default value of 250 threads is optimized for a default Tomcat configuration.  If you are using another container, especially something non-blocking like Netty, it's more appropriate to use a significantly smaller value.  Typically 25 threads would cover the needs of both the server (Netty) and the threads started by the JVM itself.
+
 #### Java Options
 
 If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to

docs/jre-zulu_jre.md

@@ -117,15 +117,15 @@ headroom: 10
 
 #### Stack Threads
 
-The amount of memory that should be allocated to stacks is given as an amount of memory per
-thread with the Java option `-Xss`. If an explicit number of
-threads should be used for the calculation of stack memory, then it should be specified as in
-the following example:
+The amount of memory that should be allocated to stacks is given as an amount of memory per thread with the Java option `-Xss`. If an explicit number of threads should be used for the calculation of stack memory, then it should be specified as in the following example:
 
 ```yaml
 stack_threads: 500
 ```
 
+Note that the default value of 250 threads is optimized for a default Tomcat configuration.  If you are using another container, especially something non-blocking like Netty, it's more appropriate to use a significantly smaller value.  Typically 25 threads would cover the needs of both the server (Netty) and the threads started by the JVM itself.hreads: 500
+```
+
 #### Java Options
 
 If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to