Skip to content

Threadpool Swiftlet

Overview

The Threadpool Swiftlet manages thread pools and event loops for asynchronous processing within the SwiftMQ router. It provides a flexible infrastructure for running tasks using both platform (traditional) and virtual (lightweight) threads, supporting high concurrency and efficient resource usage.

Features

Thread Pool Management

The Threadpool Swiftlet maintains multiple thread pools for different types of workloads. It distinguishes between platform threads (backed by operating system threads) and virtual threads (lightweight, managed by the JVM). The Swiftlet automatically creates and manages these pools, including an ad hoc platform thread pool whose size and behavior can be configured. Tasks can be executed asynchronously on either thread type, and rejected tasks are handled by a retry mechanism to ensure reliability.

Ad Hoc Platform Thread Pool

This pool is configurable for core pool size, maximum pool size, and thread keepalive time. It is used for tasks that do not belong to any specific event loop group. If the pool is exhausted, rejected tasks are queued and retried using a scheduled executor.

Ad Hoc Virtual Thread Pool

A separate pool for ad hoc tasks using virtual threads. Virtual threads provide lightweight concurrency and are managed by the JVM. The Swiftlet tracks the number of active virtual threads for monitoring purposes.

Configuration Example:

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

Event Loop Groups and Event Loops

The Swiftlet organizes event processing into groups, each containing one or more event loops. Each event loop can be configured to use either a platform or a virtual thread, and can operate in bulk mode (processing all available events per iteration) or single-event mode. Groups can be marked as freezable, allowing their event loops to be paused and resumed, which is essential for high-availability scenarios.

Group and Event Loop Configuration

Groups and their event loops are defined in the configuration. Each event loop specifies whether it uses a virtual thread and whether it operates in bulk mode. The group-shutdown-order property controls the order in which groups are shut down or frozen during router operations.

Freeze and Unfreeze Mechanism

Freezable groups can have their event loops paused (frozen) and later resumed (unfrozen). This is used during HA failover or maintenance operations to ensure a consistent state without processing new events.

Configuration Example:

<swiftlet name="sys$threadpool">
  <groups>
    <group name="io-group">
      <eventloops>
        <eventloop name="io-loop" virtual="false" bulk-mode="true"/>
      </eventloops>
    </group>
  </groups>
</swiftlet>

Thread Usage Monitoring

The Swiftlet provides real-time monitoring of active threads across all pools and event loops. It tracks the number of active platform event loop threads, virtual event loop threads, ad hoc platform threads, and ad hoc virtual threads. These metrics are updated at a configurable interval and are visible via the management interface when the admin tool is active.

Collect Interval

The collect-interval property determines how frequently the Swiftlet updates thread usage statistics. Setting this to a positive value enables periodic collection; setting it to zero or negative disables collection.

Configuration Example:

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

Group Shutdown and Startup Order

The group-shutdown-order property allows administrators to specify the order in which event loop groups are shut down or frozen. This ensures that dependent groups are handled in the correct sequence during router shutdown or HA transitions.

Configuration Example:

<swiftlet name="sys$threadpool" group-shutdown-order="io-group worker-group"/>

Configuration Guide

Customizing the Ad Hoc Platform Thread Pool

Use this scenario when you need to handle a high volume of ad hoc tasks and want to tune the thread pool for better performance or resource usage.

  1. Increase the core-pool-size and max-pool-size to allow more concurrent ad hoc tasks.
  2. Adjust the keepalive time to control how long idle threads are retained.
<swiftlet name="sys$threadpool">
  <adhocplatform core-pool-size="20" max-pool-size="100" keepalive="10000"/>
</swiftlet>

Defining a Custom Event Loop Group with Platform Threads

Use this scenario to create a dedicated event loop group that uses platform threads for specific workloads, such as I/O-bound processing.

  1. Add a new group under the groups entity.
  2. Define one or more event loops within the group, setting virtual="false" to use platform threads.
  3. Optionally, enable bulk-mode for higher throughput.
<swiftlet name="sys$threadpool">
  <groups>
    <group name="custom-group">
      <eventloops>
        <eventloop name="custom-loop" virtual="false" bulk-mode="true"/>
      </eventloops>
    </group>
  </groups>
</swiftlet>

Changing the Thread Usage Collection Interval

Adjust the interval at which thread usage statistics are collected and updated. Useful for reducing monitoring overhead or increasing monitoring frequency.

  1. Set the collect-interval attribute on the swiftlet entity to the desired interval in milliseconds.
<swiftlet name="sys$threadpool" collect-interval="5000"/>

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