<?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.StandardThreadExecutor</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>
