<?
xml version=
"1.0" encoding=
"UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!
DOCTYPE document [
<!
ENTITY project SYSTEM
"project.xml">
]>
<document
url=
"executor.html">
&project;
<properties>
<author email=
"fhanik@apache.org">Filip Hanik</author>
<title>The Executor (thread pool)</title>
</properties>
<body>
<section name=
"Table of Contents">
<toc/>
</section>
<section name=
"Introduction">
<p>The <strong>Executor</strong> represents a thread pool that can be shared
between components in Tomcat. Historically there has been a thread pool per
connector created but this allows you to share a thread pool, between (primarily) connector
but also other components when those get configured to support executors</p>
<p>The executor has to implement the <code>org.apache.catalina.Executor</code> interface.</p>
<p>The executor is a nested
element to the <a
href=
"service.html">Service</a>
element.
And in order for it to be picked up by the connectors, the Executor
element has to appear
prior to the Connector
element in server.
xml</p>
</section>
<section name=
"Attributes">
<subsection name=
"Common Attributes">
<p>All implementations of <strong>Executor</strong>
support the following attributes:</p>
<attributes>
<attribute name=
"className" required=
"false">
<p>The class of the implementation. The implementation has to implement the
<code>org.apache.catalina.Executor</code> interface.
This interface ensures that the object can be referenced through its <code>name</code> attribute
and that implements Lifecycle, so that it can be started and stopped with the container.
The default value for the className is <code>org.apache.catalina.core.StandardThreadExecu
tor</code></p>
</attribute>
<attribute name="name" required="true">
<p>The name used to reference this pool in other places in server.xml.
The name is required and must be unique.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>This implemtenation uses a pool of platform threads to execute the tasks assigned to the Executor.</p>
<p>The <code>className</code> attribute must be <code>org.apache.catalina.core.StandardThreadExecutor</code> to use
this implementation.</p>
<p>The standard implementation supports the following attributes:</p>
<attributes>
<attribute name="threadPriority" required="false">
<p>(int) The thread priority for threads in the executor, the default is
<code>5</code> (the value of the <code>Thread.NORM_PRIORITY</code> constant)</p>
</attribute>
<attribute name="daemon" required="false">
<p>(boolean) Whether the threads should be daemon threads or not, the default is <code>true</code></p>
</attribute>
<attribute name="namePrefix" required="false">
<p>(String) The name prefix for each thread created by the executor.
The thread name for an individual thread will be <code>namePrefix+threadNumber</code>. The default value is
<code>tomcat-exec-</code>.</p>
</attribute>
<attribute name="maxThreads" required="false">
<p>(int) The max number of active threads in this pool, default is <code>200</code></p>
</attribute>
<attribute name="minSpareThreads" required="false">
<p>(int) The minimum number of threads (idle and active) always kept alive, default is <code>25</code></p>
</attribute>
<attribute name="maxIdleTime" required="false">
<p>(int) The number of milliseconds before an idle thread shutsdown, unless the number of active threads are less
or equal to minSpareThreads. Default value is <code>60000</code>(1 minute)</p>
</attribute>
<attribute name="maxQueueSize" required="false">
<p>(int) The maximum number of runnable tasks that can queue up awaiting
execution before we reject them. Default value is <code>Integer.MAX_VALUE</code></p>
</attribute>
<attribute name="threadRenewalDelay" required="false">
<p>(long) If a <a href="listeners.html">ThreadLocalLeakPreventionListener</a> is configured,
it will notify this executor about stopped contexts.
After a context is stopped, threads in the pool are renewed. To avoid renewing all threads at the same time,
this option sets a delay between renewal of any 2 threads. The value is in ms,
default value is <code>1000</code> ms. If value is negative, threads are not renewed.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Virtual Thread Implementation">
<p>This implemtenation uses a new virtual thread to execute each task assigned to the Executor. This Executor requires
a minimum Java version of Java 21.</p>
<p>The <code>className</code> attribute must be <code>org.apache.catalina.core.StandardVirtualThreadExecutor</code> to
use this implementation.</p>
<p>The virtual thread implementation supports the follow attributes:</p>
<attributes>
<attribute name="namePrefix" required="false">
<p>(String) The name prefix for each thread created by the executor.
The thread name for an individual thread will be <code>namePrefix+threadNumber</code>. The default value is
<code>tomcat-virt-</code></p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>
