Skip to content

Timer Swiftlet

Overview

The Timer Swiftlet provides a centralized timer service for scheduling and executing delayed or periodic tasks within the SwiftMQ router. It manages timer listeners and ensures accurate task execution, even in the presence of system time changes. This Swiftlet is essential for internal timing operations and for other Swiftlets or components that require scheduled actions.

Features

Centralized Timer Management

The Timer Swiftlet maintains a queue of scheduled timer tasks (listeners) and dispatches them at the appropriate time. Tasks can be scheduled for one-time or repeated execution, with configurable minimum and maximum delay intervals. The Swiftlet uses a dedicated dispatcher thread, which efficiently waits for the next due task and leverages the router's thread pool for executing timer actions. Tasks are managed in a sorted queue to ensure timely and ordered execution. The timer service is used internally by other Swiftlets and components that need to perform actions after a delay or at regular intervals.

Instant and Repeating Timers

Timer listeners can be registered as instant (executed only once after the specified delay) or as repeating (automatically rescheduled after each execution). The Swiftlet provides methods to add both types of listeners, with options to control whether the timer is affected by system time changes.

System Time Change Handling

The Timer Swiftlet detects significant changes in the system clock (such as manual adjustments or NTP corrections). When a time jump is detected beyond a configurable threshold, all scheduled tasks are recalculated to maintain correct timing. Components can also register as system time change listeners to be notified when such an event occurs.

Thread-Safe Task Queue

All timer operations are thread-safe, using locks and condition variables to coordinate access to the task queue. This ensures reliable operation in a multi-threaded environment and prevents race conditions when adding, removing, or dispatching timer tasks.

Configuration Example:

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

Configurable Delay Parameters

The minimum and maximum delay intervals for timer tasks are configurable via the router configuration. The min-delay property sets the minimum allowed delay for any scheduled task, ensuring timers are not scheduled too frequently. The max-delay property defines the maximum allowed delay and also determines the threshold for detecting system time changes. These parameters can be tuned to balance timer granularity and system load.

Configuration Example:

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

Configuration Guide

Reducing Timer Granularity for High-Frequency Tasks

If your application or Swiftlets require timers to fire at a higher frequency (shorter intervals), you may need to reduce the minimum delay. This scenario is useful when precise or rapid periodic actions are required.

  1. Edit the routerconfig.xml file.
  2. Locate the sys$timer Swiftlet configuration.
  3. Set the min-delay attribute to a lower value (e.g., 50).
  4. Restart the router for the changes to take effect.
<swiftlet name="sys$timer" min-delay="50"/>

Increasing Maximum Delay for Long-Running Timers

For applications that require scheduling tasks far into the future, increase the maximum delay. This allows timer listeners to be scheduled with longer intervals before execution.

  1. Edit the routerconfig.xml file.
  2. Locate the sys$timer Swiftlet configuration.
  3. Set the max-delay attribute to a higher value (e.g., 60000 for 60 seconds).
  4. Restart the router for the changes to take effect.
<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"/>