SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk::time Namespace Reference

Time-related primitives: periodic polling, elapsed-cycle measurement and software timers. More...

Classes

class  Timer
 Abstract base class for a timer managed by TimerHost. More...
class  TimerHost
 Software timer multiplexer that manages multiple Timer instances on top of a small fixed set of kernel tasks. More...
struct  PeriodicTrigger
 Lightweight periodic trigger: returns true once per configured period when polled. More...
struct  Stopwatch
 Lightweight elapsed-cycle measurement utility. More...

Detailed Description

Time-related primitives: periodic polling, elapsed-cycle measurement and software timers.

OVERVIEW:

Class Header Description
PeriodicTrigger stk_time_util.h Polling trigger: Poll() returns true once per period. Absolute next-fire tick, no drift. No kernel tasks needed.
Stopwatch stk_time_util.h Elapsed-cycle measurement with a caller-supplied time source. Independent of any hardware counter.
TimerHost stk_time_timer.h Software timer multiplexer: many timers on a fixed set of kernel tasks (task mode) or driven by the application (polled mode).
TimerHost::Timer stk_time_timer.h Abstract timer, override OnExpired(). One-shot or periodic.

KERNEL REQUIREMENTS:

Primitive Requirements
PeriodicTrigger Kernel tick counter (GetTicks()). No tasks, no KERNEL_SYNC.
Stopwatch None. The time source is supplied by the caller.
TimerHost (task mode) KERNEL_SYNC and KERNEL_DYNAMIC (the host tasks exit on Shutdown()). Not usable with KERNEL_HRT. Occupies 1 + STK_TIMER_THREADS_COUNT task slots.
TimerHost (polled mode) KERNEL_SYNC. No tasks. Works with KERNEL_HRT.

TIMERHOST MODES:

  • Task mode (Initialize()): one tick task plus STK_TIMER_THREADS_COUNT handler tasks serve all timers, OnExpired() runs in a handler task. The weights and stacks of these tasks are set with TimerHost::Config.
  • Polled mode (InitializePolled()): no kernel tasks. The application calls Process() periodically from one context (a task loop or an HRT job). Expired callbacks run inline from Process(), which never blocks and returns the ticks until the earliest deadline (NO_WAIT if a timer is overdue, WAIT_INFINITE if none is active).

ISR / CONTEXT GUIDELINES:

Primitive Context
PeriodicTrigger Restart(), Poll(), GetPeriod(), SetPeriod(): one context only (a task or an ISR), not thread-safe.
Stopwatch Start(), Update(): one context only (a task or an ISR), not thread-safe. The supplied time source must be callable there.
TimerHost None: Initialize(), InitializePolled(), Process() and all commands (Start(), Stop(), Reset(), Restart(), StartOrReset(), SetPeriod(), Shutdown()) are called from task context.
TimerHost::Timer None: OnExpired() is never called from an ISR, it runs in a handler task (task mode) or inline in the caller of Process() (polled mode).

NOTE:

  • TimerHost commands are asynchronous: they are queued and applied by the tick task (task mode) or by the next Process() call (polled mode). They return false if the command queue is full.
  • Weights (TimerHost::Config) are strategy-specific and forwarded to the kernel unchanged. With sched::SwitchStrategyPreemptionThreshold they must be set explicitly (MakeWeight(p, p)): DEFAULT_WEIGHT decodes as priority 0 / threshold 1 and every timer task would be held while it runs.
  • Polled mode resolution is the call period of Process(): a timer fires on the first call at or after its deadline. An overdue periodic timer fires once per call until its schedule has caught up (no drift).
  • Callbacks run in the caller's context and count against its time budget. In an HRT job the worst-case time of all callbacks which can expire in one Process() call is part of the job's WCET.

WARNING:

  • TimerHost in task mode registers soft real-time tasks: a KERNEL_HRT kernel rejects them with ADD_FAIL_INVALID. Use polled mode there.
  • Do not call Process() concurrently or from OnExpired(). OnExpired() should complete quickly: a long callback delays all other expired timers (and, in polled mode, the caller of Process()).
  • Timer objects must be allocated in static storage and outlive the TimerHost, or be stopped before destruction.