Central service for time-driven scheduling of framework events. More...

#include <TimerService.h>

Collaboration diagram for TimerService:

Public Member Functions
	TimerService ()

	~TimerService ()=default

void	withLock (const std::function< void()> &fn)

void	scheduleAt (time_t unixTime, const Event &event)
	Schedule a one-time event at an absolute UNIX timestamp.

void	scheduleAt (time_t unixTime, const Event &event, const std::string &jobId)

void	scheduleEvery (uint32_t intervalMs, const Event &event)
	Schedule a repeating event at fixed intervals.

void	scheduleEvery (uint32_t intervalMs, const Event &event, const std::string &jobId)

void	scheduleDailyAt (TimeOfDay time, DaysOfWeek days, const Event &event)
	Schedule a recurring event based on time-of-day and day mask.

void	scheduleDailyAt (TimeOfDay time, DaysOfWeek days, const Event &event, const std::string &jobId)

void	scheduleDuration (TimeOfDay start, DaysOfWeek days, uint32_t durationMs, const Event &startEvent, const Event &stopEvent)
	Schedule a start event and stop event with a delay between them.

void	scheduleDuration (TimeOfDay start, DaysOfWeek days, uint32_t durationMs, const Event &startEvent, const Event &stopEvent, const std::string &baseJobId)

void	checkMissedEvents (time_t now)
	Detect and fire any missed events after a reboot (TBD).

bool	cancel (const std::string &jobId)

void	scheduleCallbackAt (time_t unixTime, std::function< void()> callback)
	Schedule a one-shot callback at a given absolute time.

Static Public Member Functions
static TimerService &	instance ()
	Access the singleton instance.

Private Member Functions
void	rescheduleDailyJob (const TimerJob &job)
	Placeholder for persistence/rescheduling in the future.

Private Attributes
SemaphoreHandle_t	lock_

std::unordered_map< std::string, TimerHandle_t >	scheduledJobs
	Map of job IDs to TimerHandles.

Static Private Attributes
static StaticSemaphore_t	lockBuffer_

Detailed Description

Definition at line 69 of file TimerService.h.

Constructor & Destructor Documentation

◆ TimerService()

TimerService::TimerService ( )

Definition at line 47 of file TimerService.cpp.

                           {
    lock_ = xSemaphoreCreateMutexStatic(&lockBuffer_);
    configASSERT(lock_);
}

References configASSERT, lock_, and lockBuffer_.

◆ ~TimerService()

TimerService::~TimerService ( )

default

Member Function Documentation

◆ cancel()

bool TimerService::cancel ( const std::string & jobId )

Definition at line 261 of file TimerService.cpp.

                                                {
    bool success = false;
    withLock([&]() {
        auto it = scheduledJobs.find(jobId);
        if (it != scheduledJobs.end()) {
            xTimerStop(it->second, 0);
            xTimerDelete(it->second, 0);
            scheduledJobs.erase(it);
            success = true;
        }
    });
    return success;
}

References scheduledJobs, and withLock().

Here is the call graph for this function:

◆ checkMissedEvents()

void TimerService::checkMissedEvents ( time_t now )

Detect and fire any missed events after a reboot (TBD).

Parameters

now	Current UNIX timestamp.

Parameters

now	Current UNIX timestamp.

Definition at line 276 of file TimerService.cpp.

{
    // Not implemented in v0.2
}

◆ instance()

TimerService & TimerService::instance ( )

static

Access the singleton instance.

Definition at line 88 of file TimerService.cpp.

{
    static TimerService inst;
    return inst;
}

◆ rescheduleDailyJob()

void TimerService::rescheduleDailyJob ( const TimerJob & job )

private

Placeholder for persistence/rescheduling in the future.

Definition at line 282 of file TimerService.cpp.

{
    // Not implemented in v0.2
}

Referenced by scheduleDailyAt(), and scheduleDuration().

Here is the caller graph for this function:

◆ scheduleAt() [1/2]

void TimerService::scheduleAt	(	time_t	unixTime,
		const Event &	event
	)

Schedule a one-time event at an absolute UNIX timestamp.

Parameters

unixTime	Epoch time in seconds.
event	Event to trigger.

Parameters

unixTime	Epoch time in seconds.
event	Event to trigger.

Definition at line 95 of file TimerService.cpp.

{
    std::string defaultId = "at_" + std::to_string(unixTime);
    scheduleAt(unixTime, event, defaultId);
}

References scheduleAt().

Referenced by scheduleAt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scheduleAt() [2/2]

void TimerService::scheduleAt	(	time_t	unixTime,
		const Event &	event,
		const std::string &	jobId
	)

Definition at line 101 of file TimerService.cpp.

{
    time_t now = PicoTime::now();
    uint32_t delaySeconds = (unixTime > now) ? (unixTime - now) : 0;
 
    TimerHandle_t handle = xTimerCreate("AtTimer", pdMS_TO_TICKS(delaySeconds * 1000), pdFALSE, new Event(event),
                                        [](TimerHandle_t xTimer)
                                        {
                                            Event *evt = static_cast<Event *>(pvTimerGetTimerID(xTimer));
                                            if (evt)
                                            {
                                                AppContext::get<EventManager>()->postEvent(*evt);
                                                delete evt;
                                            }
                                            xTimerDelete(xTimer, 0);
                                        });
 
    if (handle)
    {
        withLock([&]() {
            // Cancel and delete old timer if it exists
            auto it = scheduledJobs.find(jobId);
            if (it != scheduledJobs.end()) {
                xTimerStop(it->second, 0);
                xTimerDelete(it->second, 0);
                scheduledJobs.erase(it);
            }
            scheduledJobs[jobId] = handle;
        });
        xTimerStart(handle, 0);
    }
}

References AppContext::getTypeKey(), PicoTime::now(), scheduledJobs, and withLock().

Here is the call graph for this function:

◆ scheduleCallbackAt()

void TimerService::scheduleCallbackAt	(	time_t	unixTime,
		std::function< void()>	callback
	)

Parameters

unixTime	The absolute time to invoke the callback (in seconds).
callback	The callback to execute.

Definition at line 287 of file TimerService.cpp.

                                                                               {
    time_t now = PicoTime::now();
    if (when <= now) {
        printf("[TimerService] WARNING: scheduled time is in the past (%lld <= %lld)\n", when, now);
        return;
    }
 
    auto* cb = new std::function<void()>(std::move(callback));
    uint32_t delayMs = static_cast<uint32_t>((when - now) * 1000);
 
    TimerHandle_t handle = xTimerCreate("CbTimer", pdMS_TO_TICKS(delayMs), pdFALSE, cb,
        [](TimerHandle_t xTimer) {
            auto* fn = static_cast<std::function<void()>*>(pvTimerGetTimerID(xTimer));
            if (fn) {
                (*fn)();    // 🔥 fire the user callback
                delete fn;  // ✅ clean up
            }
            xTimerDelete(xTimer, 0);
        });
 
    if (handle) {
        xTimerStart(handle, 0);
    } else {
        printf("[TimerService] ERROR: Failed to create xTimer\n");
        delete cb;
    }
}

References PicoTime::now().

Here is the call graph for this function:

◆ scheduleDailyAt() [1/2]

void TimerService::scheduleDailyAt	(	TimeOfDay	time,
		DaysOfWeek	days,
		const Event &	event
	)

Schedule a recurring event based on time-of-day and day mask.

Parameters

time	Time of day to trigger.
days	Days to run (bitmask).
event	Event to trigger.

Parameters

time	Time of day to trigger.
days	Days to run (bitmask).
event	Event to trigger.

Definition at line 163 of file TimerService.cpp.

{
    std::string defaultId = "daily_" + std::to_string((uint32_t)event.notification.code()) + "_" + std::to_string(toSeconds(time));
    scheduleDailyAt(time, days, event, defaultId);
}

References Notification::code(), Event::notification, scheduleDailyAt(), and toSeconds().

Referenced by scheduleDailyAt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scheduleDailyAt() [2/2]

void TimerService::scheduleDailyAt	(	TimeOfDay	time,
		DaysOfWeek	days,
		const Event &	event,
		const std::string &	jobId
	)

Definition at line 169 of file TimerService.cpp.

{
    time_t now = PicoTime::now();
    uint32_t delaySeconds = secondsUntilNextMatch(time, days, now);
 
    TimerHandle_t handle = xTimerCreate("DailyJob", pdMS_TO_TICKS(delaySeconds * 1000), pdFALSE, new Event(event),
                                        [](TimerHandle_t xTimer)
                                        {
                                            Event *evt = static_cast<Event *>(pvTimerGetTimerID(xTimer));
                                            if (evt)
                                            {
                                                AppContext::get<EventManager>()->postEvent(*evt);
                                                delete evt;
                                            }
                                            xTimerDelete(xTimer, 0);
                                        });
 
    if (handle)
    {
        withLock([&]() {
            scheduledJobs[jobId] = handle;
        });        
        xTimerStart(handle, 0);
        TimerJob job{time, days, 0, event, {}, true};
        rescheduleDailyJob(job);
    }
}

References AppContext::getTypeKey(), PicoTime::now(), rescheduleDailyJob(), scheduledJobs, secondsUntilNextMatch(), and withLock().

Here is the call graph for this function:

◆ scheduleDuration() [1/2]

void TimerService::scheduleDuration	(	TimeOfDay	start,
		DaysOfWeek	days,
		uint32_t	durationMs,
		const Event &	startEvent,
		const Event &	stopEvent
	)

Schedule a start event and stop event with a delay between them.

Parameters

start	Start time of day.
days	Days to run.
durationMs	Duration after start to trigger stop.
startEvent	Event to post at start.
stopEvent	Event to post after duration.

Parameters

start	Start time of day.
days	Days to run.
durationMs	Duration after start to trigger stop.
startEvent	Event to post at start.
stopEvent	Event to post after duration.

Definition at line 198 of file TimerService.cpp.

{
    std::string baseId = "duration_" + std::to_string((uint32_t)startEvent.notification.code());
    scheduleDuration(start, days, durationMs, startEvent, stopEvent, baseId);
}

References Notification::code(), Event::notification, and scheduleDuration().

Referenced by scheduleDuration().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scheduleDuration() [2/2]

void TimerService::scheduleDuration	(	TimeOfDay	start,
		DaysOfWeek	days,
		uint32_t	durationMs,
		const Event &	startEvent,
		const Event &	stopEvent,
		const std::string &	baseJobId
	)

Definition at line 205 of file TimerService.cpp.

{
    time_t now = PicoTime::now();
    uint32_t startDelay = secondsUntilNextMatch(start, days, now);
 
    std::string startId = baseId + "_start";
    std::string stopId = baseId + "_stop";
 
    TimerHandle_t startHandle = xTimerCreate("StartJob", pdMS_TO_TICKS(startDelay * 1000), pdFALSE, new Event(startEvent),
                                             [](TimerHandle_t xTimer)
                                             {
                                                 Event *evt = static_cast<Event *>(pvTimerGetTimerID(xTimer));
                                                 if (evt)
                                                 {
                                                     AppContext::get<EventManager>()->postEvent(*evt);
                                                     delete evt;
                                                 }
                                                 xTimerDelete(xTimer, 0);
                                             });
 
    if (startHandle)
    {
        withLock([&]() {
            scheduledJobs[startId] = startHandle;
        });        
        xTimerStart(startHandle, 0);
    }
 
    uint32_t stopDelay = startDelay + durationMs / 1000;
 
    TimerHandle_t stopHandle = xTimerCreate("StopJob", pdMS_TO_TICKS(stopDelay * 1000), pdFALSE, new Event(stopEvent),
                                            [](TimerHandle_t xTimer)
                                            {
                                                Event *evt = static_cast<Event *>(pvTimerGetTimerID(xTimer));
                                                if (evt)
                                                {
                                                    AppContext::get<EventManager>()->postEvent(*evt);
                                                    delete evt;
                                                }
                                                xTimerDelete(xTimer, 0);
                                            });
 
    if (stopHandle)
    {
        withLock([&]() {
            scheduledJobs[stopId] = stopHandle;
        });   
        xTimerStart(stopHandle, 0);
    }
 
    TimerJob job{start, days, durationMs, startEvent, stopEvent, true};
    rescheduleDailyJob(job);
}

References AppContext::getTypeKey(), PicoTime::now(), rescheduleDailyJob(), scheduledJobs, secondsUntilNextMatch(), and withLock().

Here is the call graph for this function:

◆ scheduleEvery() [1/2]

void TimerService::scheduleEvery	(	uint32_t	intervalMs,
		const Event &	event
	)

Schedule a repeating event at fixed intervals.

Parameters

intervalMs	Interval in milliseconds.
event	Event to trigger repeatedly.

Parameters

intervalMs	Interval in milliseconds.
event	Event to trigger repeatedly.

Definition at line 135 of file TimerService.cpp.

{
    std::string defaultId = "interval_" + std::to_string((uint32_t)event.notification.code());
    scheduleEvery(intervalMs, event, defaultId);
}

References Notification::code(), Event::notification, and scheduleEvery().

Referenced by scheduleEvery().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scheduleEvery() [2/2]

void TimerService::scheduleEvery	(	uint32_t	intervalMs,
		const Event &	event,
		const std::string &	jobId
	)

Definition at line 141 of file TimerService.cpp.

{
    TimerHandle_t handle = xTimerCreate("EveryTimer", pdMS_TO_TICKS(intervalMs), pdTRUE, new Event(event),
                                        [](TimerHandle_t xTimer)
                                        {
                                            Event *evt = static_cast<Event *>(pvTimerGetTimerID(xTimer));
                                            if (evt)
                                            {
                                                AppContext::get<EventManager>()->postEvent(*evt);
                                            }
                                        });
 
    if (handle)
    {
        withLock([&]() {
            scheduledJobs[jobId] = handle;
        });        
        xTimerStart(handle, 0);
    }
}

References AppContext::getTypeKey(), scheduledJobs, and withLock().

Here is the call graph for this function:

◆ withLock()

void TimerService::withLock ( const std::function< void()> & fn )

Definition at line 52 of file TimerService.cpp.

                                                         {
    xSemaphoreTake(lock_, portMAX_DELAY);
    fn();
    xSemaphoreGive(lock_);
}

References lock_.

Referenced by cancel(), scheduleAt(), scheduleDailyAt(), scheduleDuration(), and scheduleEvery().

Here is the caller graph for this function:

Member Data Documentation

◆ lock_

SemaphoreHandle_t TimerService::lock_

private

Definition at line 144 of file TimerService.h.

Referenced by TimerService(), and withLock().

◆ lockBuffer_

StaticSemaphore_t TimerService::lockBuffer_

staticprivate

Note: Memory & Timer Lifetime (v0.1):

One-shot timers (scheduleAt, scheduleDailyAt, scheduleDuration) dynamically allocate an Event using new and clean it up automatically after posting (inside the timer callback).
Repeating timers (scheduleEvery) also allocate an Event, which is reused on each invocation. It is not deleted automatically and is assumed to remain valid for the lifetime of the timer.

It is now possible to cancel scheduled jobs using a job ID which will delete the timer and free the associated event.

Todo:
Planned for v0.2+:

Definition at line 145 of file TimerService.h.

Referenced by TimerService().

◆ scheduledJobs

std::unordered_map<std::string, TimerHandle_t> TimerService::scheduledJobs

private

Definition at line 147 of file TimerService.h.

Referenced by cancel(), scheduleAt(), scheduleDailyAt(), scheduleDuration(), and scheduleEvery().

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

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TimerService()

◆ ~TimerService()

Member Function Documentation

◆ cancel()

◆ checkMissedEvents()

◆ instance()

◆ rescheduleDailyJob()

◆ scheduleAt() [1/2]

◆ scheduleAt() [2/2]

◆ scheduleCallbackAt()

◆ scheduleDailyAt() [1/2]

◆ scheduleDailyAt() [2/2]

◆ scheduleDuration() [1/2]

◆ scheduleDuration() [2/2]

◆ scheduleEvery() [1/2]

◆ scheduleEvery() [2/2]

◆ withLock()

Member Data Documentation

◆ lock_

◆ lockBuffer_

◆ scheduledJobs