Skip to content

Timer Swiftlet

Overview

The Timer Swiftlet provides a centralized, high-precision timer service for the SwiftMQ router kernel and other Swiftlets. It manages scheduled tasks and listeners, ensuring accurate and efficient execution of time-based operations, even in the face of system time changes.

Features

Centralized Timer Management

The Timer Swiftlet manages a queue of scheduled tasks (timer listeners) that are executed after a specified delay. It provides both one-shot (instant) and recurring timer capabilities. Listeners can be registered to execute after a delay, and recurring listeners are automatically rescheduled after each execution unless explicitly removed. The timer queue is managed in a thread-safe manner and executed asynchronously via the system thread pool for scalability.

Instant and Recurring Timers

An instant timer listener is executed once after the specified delay, while a recurring timer listener is executed repeatedly at the given interval until removed. The Swiftlet provides methods to add both types of listeners, with optional control over whether the timer should be affected by system time changes.

Thread Pool Integration

Timer tasks are dispatched asynchronously using the system thread pool, ensuring that timer operations do not block the main dispatcher thread and can scale with the system's workload.

Configuration Example:

<swiftlet name="sys$timer" min-delay="200" max-delay="20000"/>

System Time Change Detection and Handling

The Timer Swiftlet detects significant changes in the system clock (for example, due to manual adjustments or NTP corrections). When such a change is detected, it recalculates the scheduled times of all active timer tasks to maintain correct timing behavior. Additionally, registered SystemTimeChangeListeners are notified of the detected time shift, allowing other components to react appropriately.

Time Change Threshold

The Swiftlet uses a configurable threshold (derived from the maximum delay plus a constant) to determine when a system time change is significant enough to trigger a reordering of timer tasks and notification of listeners.

Configuration Example:

<swiftlet name="sys$timer" max-delay="15000"/>

Configurable Delay Parameters

The minimum and maximum delay values for timer tasks are configurable via the Swiftlet's properties. The minimum delay determines the shortest interval the timer will use for scheduling, while the maximum delay sets an upper bound for timer intervals and influences the system time change detection threshold.

Dynamic Reconfiguration

Both the min-delay and max-delay properties can be changed at runtime. The Swiftlet listens for property changes and updates its internal scheduling parameters accordingly, allowing for flexible tuning without requiring a restart.

Configuration Example:

<swiftlet name="sys$timer" min-delay="50" max-delay="5000"/>

Configuration Guide

Reducing Timer Granularity for High-Frequency Tasks

When the application requires more frequent timer events (e.g., for rapid polling or heartbeat mechanisms), the minimum delay can be reduced to allow timers to fire at shorter intervals.

  1. Edit the routerconfig.xml file.
  2. Set the min-delay attribute on the sys$timer swiftlet to a lower value (e.g., 10).
  3. Restart the router or apply the configuration change if supported.
<swiftlet name="sys$timer" min-delay="10"/>

Handling Large System Time Adjustments

If the system clock is subject to large adjustments (for example, due to NTP corrections), increase the max-delay to ensure that timer tasks remain accurate and that the system time change detection threshold is appropriate for your environment.

  1. Edit the routerconfig.xml file.
  2. Set the max-delay attribute on the sys$timer swiftlet to a higher value (e.g., 60000 for 60 seconds).
  3. Restart the router or apply the configuration change if supported.
<swiftlet name="sys$timer" max-delay="60000"/>

Configuration Reference

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

<swiftlet name="sys$timer"> Properties

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

Parameter Type Default Mandatory Reboot Required Description
min-delay Long 100 No No Minimum Delay (min: 0)
max-delay Long 10000 No No Maximum Delay (min: 1000) 
<swiftlet name="sys$timer" min-delay="100" max-delay="10000"/>