Skip to content

Svc::LinuxTimer

1. Introduction

The LinuxTimer component provides a periodic tick source for Linux and Darwin systems. It implements the Drv.Tick interface, invoking its CycleOut output port at a fixed interval. It is typically connected to a Svc::RateGroupDriver to drive the rate groups of a deployment, serving the same role as a hardware timer interrupt does on embedded platforms.

2. Requirements

Name Description Validation
SVC-LINUXTIMER-001 The LinuxTimer component shall implement the Drv.Tick interface inspection
SVC-LINUXTIMER-002 The LinuxTimer component shall invoke its CycleOut port at a caller-specified fixed interval unit test
SVC-LINUXTIMER-003 The LinuxTimer component shall provide a timestamp of the tick with each CycleOut invocation inspection
SVC-LINUXTIMER-004 The LinuxTimer component shall stop ticking when quit() is called unit test

3. Design

The LinuxTimer is a passive component with no thread of its own. The caller's thread — typically the deployment's main thread after topology startup — is donated to the timer by calling startTimer(), which blocks in the timer loop until quit() is called from another thread.

3.1 Port Description

Port Kind Type Description
CycleOut output Svc.Cycle Periodic tick output; meant to be connected to a rate group driver

The component has no commands, events, telemetry, or parameters.

3.2 Implementations

Two implementations are provided; the build selects one based on the target platform (see CMakeLists.txt):

  • timerfd (Linux) — LinuxTimerFd.cpp creates a timerfd on CLOCK_MONOTONIC set to the requested interval and blocks on read() for each expiration. This provides drift-free periodic ticks, since the kernel maintains the expiration schedule.
  • Task delay (Darwin) — LinuxTimerTaskDelay.cpp sleeps for the interval between ticks using a task delay. This is subject to accumulated drift and is intended for development hosts without timerfd support.

On each tick, the implementation captures a raw timestamp (Os::RawTime) and invokes CycleOut. The loop checks the mutex-protected quit flag each iteration and returns when it is set.

4. Usage

  1. Instantiate the component in the topology and connect CycleOut to the rate group driver's cycle input.
  2. Start the timer from deployment startup code, donating the calling thread: linuxTimer.startTimer(Fw::TimeInterval(0, 100000)) for a 100 ms (10 Hz) tick. This call blocks.
  3. Shut down by calling linuxTimer.quit() from an exit handler; startTimer then returns and the deployment can tear down.

5. Change Log

Date Description
2026-08-10 Initial SDD