foresthub::util::Ticker Class Reference

Unified timing class for periodic, one-shot, and calendar-aligned scheduling. More...

#include <ticker.hpp>

Public Member Functions
	Ticker (unsigned long period, long offset=0)
	Construct a Ticker with custom period and offset.
Ticker &	WithMaxFires (unsigned long n)
	Set the maximum number of fires before auto-stopping (0 = unlimited).
Ticker &	WithTimezoneOffset (long tz_offset_sec)
	Set timezone offset for calendar-based scheduling (Daily/Weekly/Hourly).
void	Start (unsigned long time)
	Start (or restart) the ticker with the given time reference.
bool	Check (unsigned long time)
	Check if the ticker should fire at the given time.
void	Stop ()
	Stop the ticker. Call Start() to restart.
void	SetTimezoneOffset (long tz_offset_sec)
	Update timezone offset at runtime (e.g., after DST transition).
bool	running () const
	Whether the ticker is currently running.
unsigned long	fire_count () const
	Number of times the ticker has fired since last Start().
unsigned long	missed_ticks () const
	Number of intervals skipped in the last Check() that fired.
unsigned long	period () const
	Configured period in time units.
long	tz_offset_sec () const
	Configured timezone offset in seconds (0 if not set).

Static Public Member Functions
static Ticker	Periodic (unsigned long interval)
	Create a periodic ticker that fires at a fixed interval.
static Ticker	OneShot (unsigned long delay)
	Create a one-shot timer that fires exactly once after a delay.
static Ticker	Daily (int hour, int minute=0)
	Create a daily ticker that fires once per day at a specific hour and minute.
static Ticker	Weekly (int weekday, int hour, int minute=0)
	Create a weekly ticker that fires once per week on a specific day and time.
static Ticker	Hourly (int minute=0)
	Create an hourly ticker that fires once per hour at a specific minute.

Detailed Description

Unified timing class for periodic, one-shot, and calendar-aligned scheduling.

Platform-independent — takes any unsigned long time source. Two evaluation paths:

• Relative (Periodic/OneShot): Uses unsigned subtraction (time - start_time_). Wrap-safe for 32-bit unsigned overflow. Drift correction maintains cadence after gaps.
• Absolute (Daily/Weekly/Hourly): Uses signed slot math (FloorDiv(time + offset, period)). Calendar-aligned via epoch seconds. No <ctime> dependency.

Factory methods create pre-configured instances for common patterns. The caller provides the current time to Check(time) — the Ticker decides internally whether to use relative or absolute evaluation.

// Periodic: read sensor every 5 seconds (now_ms = any millisecond source)
auto ticker = Ticker::Periodic(5000);
ticker.Start(now_ms);
if (ticker.Check(now_ms)) { readSensor(); }
 
// Daily: sync data at 14:00 Berlin time (now_epoch = UTC epoch seconds)
auto daily = Ticker::Daily(14, 0).WithTimezoneOffset(3600);
daily.Start(now_epoch);
if (daily.Check(now_epoch)) { syncData(); }
 
// OneShot: timeout after 30 seconds
auto timeout = Ticker::OneShot(30000);
timeout.Start(now_ms);
if (timeout.Check(now_ms)) { handleTimeout(); }

Constructor & Destructor Documentation

Ticker()

foresthub::util::Ticker::Ticker ( unsigned long period, long offset = 0 )

inlineexplicit

Construct a Ticker with custom period and offset.

For most use cases, prefer the static factory methods (Daily, Weekly, Hourly, Periodic, OneShot).

Parameters

period	Period in time units (seconds for calendar-based, milliseconds for relative).
offset	Internal offset for slot calculation (calendar-based scheduling only).

Member Function Documentation

Check()

bool foresthub::util::Ticker::Check ( unsigned long time )

inline

Check if the ticker should fire at the given time.

Returns true at most once per period. After a long gap, fires once and reports the number of skipped intervals via missed_ticks().

Parameters

time	Current time value (same unit as Start()).

Daily()

Ticker foresthub::util::Ticker::Daily ( int hour, int minute = 0 )

inlinestatic

Create a daily ticker that fires once per day at a specific hour and minute.

Uses absolute mode with epoch seconds. For local time scheduling, use WithTimezoneOffset(utc_offset_sec) and pass raw UTC epoch to Check().

Parameters

hour	Hour of day (0-23).
minute	Minute of hour (0-59).

Hourly()

Ticker foresthub::util::Ticker::Hourly ( int minute = 0 )

inlinestatic

Create an hourly ticker that fires once per hour at a specific minute.

Parameters

minute

Minute of hour (0-59).

missed_ticks()

unsigned long foresthub::util::Ticker::missed_ticks ( ) const

inline

Number of intervals skipped in the last Check() that fired.

Returns 0 when Check() fires on time. Only meaningful after a Check() that returned true.

OneShot()

Ticker foresthub::util::Ticker::OneShot ( unsigned long delay )

inlinestatic

Create a one-shot timer that fires exactly once after a delay.

Equivalent to Periodic(delay).WithMaxFires(1).

Parameters

delay

Delay before firing (same unit as Periodic interval).

Periodic()

Ticker foresthub::util::Ticker::Periodic ( unsigned long interval )

inlinestatic

Create a periodic ticker that fires at a fixed interval.

Uses relative mode (wrap-safe unsigned subtraction). Time unit is determined by the caller (e.g., milliseconds or ticks).

Parameters

interval

Interval between fires (e.g., 5000 for 5 seconds at millisecond resolution).

SetTimezoneOffset()

void foresthub::util::Ticker::SetTimezoneOffset ( long tz_offset_sec )

inline

Update timezone offset at runtime (e.g., after DST transition).

Parameters

tz_offset_sec

Total timezone offset from UTC in seconds.

Start()

void foresthub::util::Ticker::Start ( unsigned long time )

inline

Start (or restart) the ticker with the given time reference.

Resets fire_count and missed ticks. For relative mode, pass a millisecond or tick counter. For calendar-based mode, pass UTC epoch seconds.

Parameters

time	Current time value.

Weekly()

Ticker foresthub::util::Ticker::Weekly ( int weekday, int hour, int minute = 0 )

inlinestatic

Create a weekly ticker that fires once per week on a specific day and time.

Parameters

weekday	Day of week (0=Sunday, 1=Monday, ..., 6=Saturday).
hour	Hour of day (0-23).
minute	Minute of hour (0-59).

WithTimezoneOffset()

Ticker & foresthub::util::Ticker::WithTimezoneOffset ( long tz_offset_sec )

inline

Set timezone offset for calendar-based scheduling (Daily/Weekly/Hourly).

Applied internally in slot calculation — pass raw UTC epoch to Start()/Check(). Mutually exclusive with manual offset addition at the call site. For DST changes at runtime, use SetTimezoneOffset().

Parameters

tz_offset_sec

Total timezone offset from UTC in seconds (e.g., 7200 for CEST).

---

The documentation for this class was generated from the following file:

• include/foresthub/util/ticker.hpp