Skip to content

Threadpool Swiftlet

Overview

The Threadpool Swiftlet manages all thread pools and event loops used within the SwiftMQ router. It provides flexible configuration of thread execution models, including support for both platform (OS) threads and virtual threads, and enables fine-grained control over event loop grouping, freezing, and shutdown order for high availability and performance tuning.

Features

Thread Pool Management

The Threadpool Swiftlet provides and manages multiple thread pools for different execution scenarios within the router. It supports both platform threads (traditional OS threads) and virtual threads (lightweight threads introduced in modern Java versions). The Swiftlet maintains separate runners for ad hoc platform and virtual threads, as well as for event loop execution. Thread pools can be configured for core and maximum pool sizes, as well as thread keepalive times. A custom rejection handler ensures that tasks rejected due to pool saturation are retried, preventing task loss under heavy load.

Ad Hoc Platform Thread Pool

Configurable via the adhocplatform entity, this pool handles tasks that require traditional platform threads. Parameters such as core-pool-size, max-pool-size, and keepalive determine the pool's behavior and resource usage.

Ad Hoc Virtual Thread Pool

This pool uses Java virtual threads for lightweight, high-concurrency task execution. It is automatically managed and does not require explicit sizing parameters.

Configuration Example:

<swiftlet name="sys$threadpool">
  <adhocplatform core-pool-size="4" max-pool-size="50" keepalive="2000"/>
</swiftlet>

Event Loop Groups and Assignment

The Swiftlet allows the definition of event loop groups, each containing one or more event loops. Each event loop can be assigned to use either a platform thread or a virtual thread, and can be configured to operate in bulk mode (processing all available events in one iteration) or single-event mode. Groups can be marked as freezable, enabling coordinated freeze/unfreeze operations for high availability scenarios. The shutdown order of groups can be explicitly controlled for graceful router shutdown.

Group and Event Loop Configuration

Groups are defined under the groups entity list, with each group containing its own list of event loops. Each event loop specifies whether it uses virtual threads (virtual="true") and whether it operates in bulk mode (bulk-mode="true").

Freezable Groups

Groups can be marked as freezable (freezable="true"), allowing all event loops in the group to be frozen and unfrozen as a unit. This is essential for coordinated state transitions in high availability deployments.

Shutdown Order

The group-shutdown-order property specifies the order in which groups are shut down during router shutdown, ensuring dependencies are respected and resources are released in a controlled manner.

Configuration Example:

<swiftlet name="sys$threadpool" group-shutdown-order="group1 group2">
  <groups>
    <group name="group1" freezable="true">
      <eventloops>
        <eventloop name="loop1" virtual="false" bulk-mode="true"/>
      </eventloops>
    </group>
    <group name="group2" freezable="false">
      <eventloops>
        <eventloop name="loop2" virtual="true" bulk-mode="false"/>
      </eventloops>
    </group>
  </groups>
</swiftlet>

Thread Usage Monitoring and Collection

The Swiftlet periodically collects and exposes statistics on active threads across all thread pools and event loops. The collection interval is configurable via the collect-interval property. Usage statistics are available under the usage entity list, providing real-time insight into the number of active platform, virtual, ad hoc platform, and ad hoc virtual threads. This information is useful for monitoring, tuning, and troubleshooting thread utilization in the router.

Configuration Example:

<swiftlet name="sys$threadpool" collect-interval="5000"/>

Freeze and Unfreeze Operations

The Threadpool Swiftlet supports coordinated freeze and unfreeze operations for event loop groups marked as freezable. Freezing a group causes all its event loops to pause event processing, which is essential for high availability failover or maintenance scenarios. Unfreezing resumes normal event processing. These operations are performed in the order specified by group-shutdown-order to ensure consistency and avoid deadlocks.

Configuration Guide

Customizing Ad Hoc Platform Thread Pool

Use this scenario to increase the maximum number of platform threads available for ad hoc tasks, which can help in environments with high concurrency requirements or heavy workloads.

  1. Navigate to the Threadpool Swiftlet configuration section in routerconfig.xml.
  2. Set the core-pool-size, max-pool-size, and keepalive attributes under the adhocplatform entity to desired values.
  3. Restart the router if necessary to apply changes.
<swiftlet name="sys$threadpool">
  <adhocplatform core-pool-size="8" max-pool-size="100" keepalive="5000"/>
</swiftlet>

Defining a Custom Event Loop Group with Mixed Thread Types

This scenario demonstrates how to define a group with both platform and virtual thread event loops, and control their bulk mode behavior.

  1. In routerconfig.xml, add a new group under the groups entity list.
  2. Add event loops to the group, specifying virtual and bulk-mode attributes as needed.
  3. Optionally, set freezable to control HA behavior.
<swiftlet name="sys$threadpool">
  <groups>
    <group name="processing" freezable="true">
      <eventloops>
        <eventloop name="fastloop" virtual="true" bulk-mode="true"/>
        <eventloop name="slowloop" virtual="false" bulk-mode="false"/>
      </eventloops>
    </group>
  </groups>
</swiftlet>

Changing the Group Shutdown Order

Adjust the shutdown sequence of event loop groups to ensure that dependent services are stopped in the correct order during router shutdown.

  1. Edit the group-shutdown-order attribute on the Threadpool Swiftlet entity.
  2. List group names in the desired shutdown sequence, separated by spaces.
  3. Restart the router for the change to take effect.
<swiftlet name="sys$threadpool" group-shutdown-order="groupA groupB groupC"/>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$threadpool">.

<swiftlet name="sys$threadpool"> Properties

These properties are attributes of the <swiftlet name="sys$threadpool"> entity.

Parameter Type Default Mandatory Reboot Required Description
collect-interval Long 1000 No No Interval for collecting the Thread Counts
group-shutdown-order String — No Yes The order in which the groups are being shut down 
<swiftlet name="sys$threadpool" collect-interval="1000"/>

<adhocplatform> Entity

Configures the Ad Hoc Platform Thread Factory

This is a fixed child entity of <swiftlet name="sys$threadpool">.

Parameter Type Default Mandatory Reboot Required Description
core-pool-size Integer 0 No No Minimum number of threads to keep in the pool (min: 0)
max-pool-size Integer 30 No No Maximum number of threads in the pool (min: 20)
keepalive Long 1000 No No Keep alive time for idle threads in milliseconds (min: 1000) 
<swiftlet name="sys$threadpool">
  <adhocplatform core-pool-size="..." max-pool-size="..." keepalive="..."/>
</swiftlet>

<groups> in <swiftlet name="sys$threadpool">

Event Loop Groups

Each <group> entry is identified by its name attribute (the Group).

Parameter Type Default Mandatory Reboot Required Description
freezable Boolean true No No If true, the groups event loops can be frozen for HA 
<swiftlet name="sys$threadpool">
  <groups>
    <group name="..."/>
  </groups>
</swiftlet>

<eventloops> in <groups>

Event Loop Assignments

Each <eventloop> entry is identified by its name attribute (the Event Loop).

Parameter Type Default Mandatory Reboot Required Description
virtual Boolean true No No Uses a Virtual Threads for this Event Loop, otherwise a Platform Thread
bulk-mode Boolean false No No Consumes all available events or a single event in one iteration 
<swiftlet name="sys$threadpool">
  <groups>
    <group name="...">
      <eventloops>
        <eventloop name="..."/>
      </eventloops>
    </group>
  </groups>
</swiftlet>

Changelog

13.1.0 (2025-01-16)

  • Modified configuration
  • Modified VirtualThreadRunner