Merge pull request #4262 from vespa-engine/johsol/default-threadpool-documentation

Container Default Threadpool Documentation

Author: johansolbakken

en/performance/container-tuning.html

@@ -17,7 +17,8 @@
 <h2 id="container-worker-threads">Container worker threads</h2>
 <p>
   The container uses multiple thread pools for its operations.
-  Most components including request handlers use the container's <em>default thread pool</em>,
+  Most components including request handlers use the container's
+  <a href="../reference/services-container.html#threadpool">default thread pool</a>,
   which is controlled by a shared executor instance.
   Any component can utilize the default pool by injecting an <code>java.util.concurrent.Executor</code> instance.
   Some built-in components have dedicated thread pools - such as the Jetty server, the
@@ -31,7 +32,8 @@ <h2 id="container-worker-threads">Container worker threads</h2>
   (<code>Runtime.getRuntime().availableProcessors()</code>).
   It's paramount that the <code>-XX:ActiveProcessorCount</code>/<code>jvm_availableProcessors</code>
   configuration is correct for the container to work optimally.
-  The default thread pool configuration can be overridden through services.xml.
+  The <a href="../reference/services-container.html#threadpool">default thread pool</a> configuration can be
+  overridden through services.xml.
   We recommend you keep the default configuration as it's tuned to work across a variety of workloads.
   Note that the default configuration and pool usage may change between minor versions.
 </p>
@@ -83,6 +85,17 @@ <h3 id="container-worker-threads-example">Example</h3>
 <pre>{% highlight xml %}
 <container id="container" version="1.0">
 
+    <!-- The containers default thread pool -->
+    <threadpool>
+        <!-- Note: relative values -->
+
+        <!-- 5 threads per vcpu => 40 threads on 8 vcpu -->
+        <threads max="5">5</threads>
+
+        <!-- 25 queue slots per thread => 1000 entries on 8 vcpu -->
+        <queue>25</queue>
+    </threadpool>
+
     <search>
         <!-- Search handler thread pool -->
         <threadpool>
@@ -104,14 +117,6 @@ <h3 id="container-worker-threads-example">Example</h3>
         </threadpool>
     </document-processing>
 
-    <!-- Default thread pool -->
-    <config name="container.handler.threadpool">
-        <!-- Set corePoolSize==maxthreads for fixed size pool (recommended) -->
-        <!-- Note: absolute pool size -->
-        <corePoolSize>1000</corePoolSize>
-        <maxthreads>1000</maxthreads>
-    </config>
-
 </container>
 {% endhighlight %}</pre>
 

en/reference/services-container.html

@@ -68,6 +68,7 @@
     <a href="#secret-store">secret-store [type]</a>
         <a href="#group">group [name, environment]</a>
     <a href="#zookeeper">zookeeper</a>
+    <a href="#threadpool">threadpool</a>
 </pre>
 
 <p><a href="config-files.html#generic-configuration-in-services-xml">config</a> elements are also allowed most places.</p>
@@ -813,3 +814,43 @@ <h2 id="zookeeper">zookeeper</h2>
   and configure the necessary components.
   This element has no attributes or children.
 </p>
+
+
+<h2 id="threadpool">threadpool</h2>
+<p>
+  Available since {% include version.html version="8.611.13" %}.
+</p>
+<p>
+  Specifies configuration for the default thread pool in the container.
+  All parameters are relative to the number of CPU cores—see the
+  <a href="../performance/container-tuning.html#container-worker-threads-example">container tuning example</a>.
+  This thread pool also supports the optional <code>max</code> attribute, which lets the pool grow up to
+  <code>max * vCPU</code> threads under load before shrinking back after 5 seconds of idleness. Requests are rejected once the allowed
+  number of threads is reached, all are busy, and the queue is full.
+</p>
+
+<h3 id="threadpool-threads">threads</h3>
+<p>
+  The number of permanent threads relative to number of vCPU cores. Default value is <code>2</code>.
+</p>
+<table class="table">
+  <thead>
+  <tr><th>Attribute</th><th>Required</th><th>Value</th><th>Default</th><th>Description</th></tr>
+  </thead><tbody>
+<tr><th>max</th>
+  <td>optional</td>
+  <td>number</td>
+  <td>100</td>
+  <td>
+    <p id="threads.max">
+      The maximum number of threads relative to vCPU cores. Value must be greater than or equal to <code>&lt;threads&gt;</code>.
+    </p>
+  </td></tr>
+</tbody>
+</table>
+
+<h3 id="threadpool-queue">queue</h3>
+<p>
+  The size of the request queue relative to effective number of threads.
+  Specify <code>0</code> to disable queuing. Queueing is disabled by default.
+</p>

en/reference/services-search.html

@@ -545,11 +545,11 @@ <h3 id="threadpool-threads">threads</h3>
 <tr><th>max</th>
   <td>optional</td>
   <td>number</td>
-  <td></td>
+  <td>equal to <code>&lt;threads&gt;</code></td>
   <td>
     <span id="threads.boost"></span>
     <p id="threads.max">
-      The maximum number of threads relative to vCPU cores. Defaults to <code>&lt;threads&gt;</code> (no dynamic scaling), and must be greater than or equal to <code>&lt;threads&gt;</code>.
+      The maximum number of threads relative to vCPU cores. Value must be greater than or equal to <code>&lt;threads&gt;</code>.
     </p>
   </td></tr>
 </tbody>