Software timer multiplexer that manages multiple Timer instances on top of a small fixed set of kernel tasks. More...

#include <stk_time_timer.h>

Collaboration diagram for stk::time::TimerHost:

Classes
class	Timer
	Abstract base class for a timer managed by TimerHost. More...
class	TimerWorkerTask
	Internal kernel task used by TimerHost for both the tick task and handler tasks. More...
struct	TimerCommand
	POD command record passed from the public API methods to the tick task via the command queue. More...

Public Types
enum	EConsts : size_t { TASK_COUNT = (1U + 1U ) , TASK_TICK_MEMORY_SIZE = Max<size_t>(256U, STK_STACK_SIZE_MIN) , TASK_HANDLER_STACK_SIZE = Max<size_t>( 256U , STK_STACK_SIZE_MIN) }

Public Member Functions
	TimerHost ()
	Default constructor. Zero-initializes all internal state.
	~TimerHost ()=default
	Destructor.
void	Initialize (IKernel *kernel, EAccessMode mode)
	Initialize timer host instance.
bool	Start (Timer &tmr, uint32_t delay, uint32_t period=0)
	Start timer.
bool	Stop (Timer &tmr)
	Stop running timer.
bool	Reset (Timer &tmr)
	Reset periodic timer's deadline.
bool	Restart (Timer &tmr, uint32_t delay, uint32_t period=0)
	Atomically stop and re-start timer.
bool	StartOrReset (Timer &tmr, uint32_t delay, uint32_t period=0)
	Start timer if inactive, or reset its deadline if already active and periodic.
bool	SetPeriod (Timer &tmr, uint32_t period)
	Change the period of a running periodic timer without affecting its current deadline.
bool	IsEmpty () const
	Return true if no timers are currently active.
size_t	GetSize () const
	Return number of currently active timers.
bool	Shutdown ()
	Shutdown host instance. All timers are stopped and removed from the host.
Ticks	GetTimeNow () const
	Get current time.

Private Types
typedef void(*	TimerFuncType) (TimerHost *host)
	Timer task function prototype.
typedef StackMemoryDef< TASK_TICK_MEMORY_SIZE >::Type	TaskTickMemory
	Stack memory type for the single tick task.
typedef StackMemoryDef< TASK_HANDLER_STACK_SIZE >::Type	TimerHostMemory
	Stack memory type for each handler task.
typedef sync::PipeT< Timer *, 32U >	ReadyQueue
	Lock-free pipe used to transfer expired timer pointers from the tick task to handler tasks.
typedef sync::PipeT< TimerCommand, 32U >	CommandQueue
	Lock-free pipe used to send TimerCommand records from API callers to the tick task.

Private Member Functions
	STK_NONCOPYABLE_CLASS (TimerHost)
void	UpdateTime ()
	Tick task body: drives the timer list and dispatches expired timers.
void	ProcessTimers ()
	Handler task body: dequeues expired timers and invokes their OnExpired() callbacks.
bool	ProcessCommands (Timeout next_sleep)
	Drain the command queue and execute each pending command.
bool	PushCommand (TimerCommand cmd)
	Enqueue a command for the tick task.

Private Attributes
TaskTickMemory	m_task_tick_memory
	tick task memory
TimerHostMemory	m_task_handler_memory [1U]
	handler task memory
TimerWorkerTask	m_task_tick
	timer task
TimerWorkerTask	m_task_process [1U]
	handler tasks
util::DListHead< Timer, false >	m_active
	active timers (tick task only)
ReadyQueue	m_queue
	queue of timers ready for handling
CommandQueue	m_commands
	command queue
Ticks	m_now
	last known current time (ticks)

Detailed Description

Software timer multiplexer that manages multiple Timer instances on top of a small fixed set of kernel tasks.

TimerHost internally runs two categories of tasks:

One tick task that maintains the active timer list, evaluates deadlines every wake cycle, and queues expired timers for dispatch.
One or more handler tasks (see STK_TIMER_THREADS_COUNT) that dequeue expired timers and invoke their OnExpired() callbacks.

All timers share the same tick and handler tasks, so the total kernel task overhead is constant regardless of how many timers are active.

Two timer modes are supported:

One-shot: fires once after delay ticks and becomes inactive automatically.
Periodic: fires every period ticks until explicitly stopped.

Note: TimerHost must be initialized before use by calling Initialize(). The maximum number of concurrently active timers is STK_TIMER_COUNT_MAX (default: 32). The maximum timer period is bounded by uint32_t (~49 days at 1 ms resolution).

// define a concrete timer by overriding OnExpired
class HeartbeatTimer : public stk::time::TimerHost::Timer
{
public:
    void OnExpired(stk::time::TimerHost *host)
    {
        // called every 500 ms
        ToggleLed();
    }
};
 
// declare host and timer instances (static storage, no heap)
stk::time::TimerHost  g_TimerHost;
HeartbeatTimer        g_Heartbeat;
 
// one-shot example: send a delayed notification
class NotifyTimer : public stk::time::TimerHost::Timer
{
public:
    void OnExpired(stk::time::TimerHost *host)
    {
        g_Event.Signal();
    }
};
 
NotifyTimer g_Notify;
 
void SetupTimers(stk::IKernel *kernel)
{
    // initialize the host, must be called before Start()
    g_TimerHost.Initialize(kernel, stk::ACCESS_USER);
 
    // start 500 ms periodic heartbeat
    uint32_t period = stk::GetTicksFromMsec(500);
    g_TimerHost.Start(g_Heartbeat, period, period);
 
    // start a one-shot notification after 1 second
    uint32_t delay = stk::GetTicksFromMsec(1000);
    g_TimerHost.Start(g_Notify, delay);
}

See also: TimerHost::Timer, STK_TIMER_THREADS_COUNT, STK_TIMER_HANDLER_STACK_SIZE, STK_TIMER_COUNT_MAX

Definition at line 111 of file stk_time_timer.h.

Member Typedef Documentation

◆ CommandQueue

typedef sync::PipeT<TimerCommand, 32U > stk::time::TimerHost::CommandQueue

private

Lock-free pipe used to send TimerCommand records from API callers to the tick task.

Definition at line 461 of file stk_time_timer.h.

◆ ReadyQueue

typedef sync::PipeT<Timer *, 32U > stk::time::TimerHost::ReadyQueue

private

Lock-free pipe used to transfer expired timer pointers from the tick task to handler tasks.

Definition at line 456 of file stk_time_timer.h.

◆ TaskTickMemory

typedef StackMemoryDef<TASK_TICK_MEMORY_SIZE>::Type stk::time::TimerHost::TaskTickMemory

private

Stack memory type for the single tick task.

Definition at line 446 of file stk_time_timer.h.

◆ TimerFuncType

typedef void(* stk::time::TimerHost::TimerFuncType) (TimerHost *host)

private

Timer task function prototype.

Definition at line 318 of file stk_time_timer.h.

◆ TimerHostMemory

typedef StackMemoryDef<TASK_HANDLER_STACK_SIZE>::Type stk::time::TimerHost::TimerHostMemory

private

Stack memory type for each handler task.

Definition at line 451 of file stk_time_timer.h.

Member Enumeration Documentation

◆ EConsts

enum stk::time::TimerHost::EConsts : size_t

Enumerator

TASK_COUNT

total number of tasks serving this instance

stack memory size of the tick task

TASK_TICK_MEMORY_SIZE

stack memory size of the timer handler task

TASK_HANDLER_STACK_SIZE

Definition at line 114 of file stk_time_timer.h.

    {
        TASK_COUNT = (1U + STK_TIMER_THREADS_COUNT),
        TASK_TICK_MEMORY_SIZE = Max<size_t>(256U, STK_STACK_SIZE_MIN),
        TASK_HANDLER_STACK_SIZE = Max<size_t>(STK_TIMER_HANDLER_STACK_SIZE, STK_STACK_SIZE_MIN)
    };

Constructor & Destructor Documentation

◆ TimerHost()

stk::time::TimerHost::TimerHost ( )

inlineexplicit

Default constructor. Zero-initializes all internal state.

Note: Call Initialize() before using any other member function.

Definition at line 215 of file stk_time_timer.h.

      : m_task_tick_memory(), m_task_handler_memory(), m_task_tick(), m_task_process(), 
        m_active(), m_now(0)
    {}

References m_active, m_now, m_task_handler_memory, m_task_process, m_task_tick, and m_task_tick_memory.

Referenced by Initialize(), stk::time::TimerHost::TimerWorkerTask::Initialize(), and STK_NONCOPYABLE_CLASS().

Here is the caller graph for this function:

◆ ~TimerHost()

stk::time::TimerHost::~TimerHost ( )

default

Destructor.

Note: MISRA deviation: [STK-DEV-005] Rule 10-3-2.

Member Function Documentation

◆ GetSize()

size_t stk::time::TimerHost::GetSize ( ) const

inline

Return number of currently active timers.

Returns: Active timer count.

Note: The value is advisory and may change immediately after the call.

Definition at line 300 of file stk_time_timer.h.

300{ return m_active.GetSize(); }

References m_active.

Referenced by stk_timerhost_get_size().

Here is the caller graph for this function:

◆ GetTimeNow()

Ticks stk::time::TimerHost::GetTimeNow ( ) const

inline

Get current time.

Returns: Current time (ticks).

Definition at line 310 of file stk_time_timer.h.

310{ return hw::ReadVolatile64(&m_now); }

stk::hw::ReadVolatile64

static T ReadVolatile64(volatile const T *addr)

Atomically read a 64-bit volatile value.

Definition stk_arch.h:331

References m_now, and stk::hw::ReadVolatile64().

Referenced by stk_timerhost_get_time_now().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Initialize()

void stk::time::TimerHost::Initialize	(	IKernel *	kernel,
		EAccessMode	mode )

inline

Initialize timer host instance.

Parameters

[in]	kernel	Kernel to which instance will be bound.
[in]	mode	Access mode for the timer handling tasks which call expired timers.

Definition at line 501 of file stk_time_timer.h.

{
    for (size_t i = 0U; i < STK_TIMER_THREADS_COUNT; ++i)
    {
        m_task_process[i].Initialize(this, m_task_handler_memory[i], TASK_HANDLER_STACK_SIZE, mode, [](TimerHost *host)
        {
            host->ProcessTimers();
        });
        kernel->AddTask(&m_task_process[i]);
    }
 
    m_task_tick.Initialize(this, m_task_tick_memory, TASK_TICK_MEMORY_SIZE, ACCESS_USER, [](TimerHost *host)
    {
        host->UpdateTime();
    });
    kernel->AddTask(&m_task_tick);
}

References stk::ACCESS_USER, stk::IKernel::AddTask(), m_task_handler_memory, m_task_process, m_task_tick, m_task_tick_memory, ProcessTimers(), STK_TIMER_THREADS_COUNT, TASK_HANDLER_STACK_SIZE, TASK_TICK_MEMORY_SIZE, TimerHost(), and UpdateTime().

Referenced by stk::interop_c_helper::InitializeTimerHost().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ IsEmpty()

bool stk::time::TimerHost::IsEmpty ( ) const

inline

Return true if no timers are currently active.

Returns: True if active timer count is zero.

Note: The value is advisory and may change immediately after the call.

Definition at line 294 of file stk_time_timer.h.

294{ return m_active.IsEmpty(); }

References m_active.

Referenced by stk_timerhost_is_empty().

Here is the caller graph for this function:

◆ ProcessCommands()

bool stk::time::TimerHost::ProcessCommands ( Timeout next_sleep )

inlineprivate

Drain the command queue and execute each pending command.

Parameters

[in] next_sleep Maximum ticks to block waiting for the first command when the active list is non-empty. Overridden to WAIT_INFINITE when empty.

Returns: True to continue the tick loop; false when CMD_SHUTDOWN is processed.

Note: Called exclusively from the tick task (UpdateTime()).

Definition at line 813 of file stk_time_timer.h.

{
    TimerCommand cmd = {};
    bool working = true;
 
    // if nothing is active, sleep indefinitely until a command arrives
    if (m_active.IsEmpty())
    {
        next_sleep = WAIT_INFINITE;
    }
 
    while (working)
    {
        if (!m_commands.Read(cmd, next_sleep))
        {
            break;
        }
      
        switch (cmd.cmd)
        {
        case TimerCommand::CMD_START: 
        {
            Timer *const tmr = cmd.timer;
            STK_ASSERT(tmr != nullptr);
 
            // reject if already active or linked (double-start)
            if (!tmr->m_active)
            {
                STK_ASSERT(!tmr->IsLinked());
 
                tmr->m_deadline = cmd.timestamp + static_cast<Ticks>(cmd.delay);
                tmr->m_period   = cmd.period;
                tmr->m_active   = true;
                tmr->m_pending  = false;
 
                m_active.LinkBack(tmr);
                next_sleep = NO_WAIT;
            }
            
        break; }
 
        case TimerCommand::CMD_STOP:
        {
            Timer *const tmr = cmd.timer;
            STK_ASSERT(tmr != nullptr);
 
            tmr->m_active  = false;
            tmr->m_pending = false;
 
            // allow possibly duplicate CMD_STOP as it is harmless for the logic
            if (tmr->IsLinked())
            {
                m_active.Unlink(tmr);
            }
            
        break; }
 
        case TimerCommand::CMD_RESET:
        {
            Timer *const tmr = cmd.timer;
            STK_ASSERT(tmr != nullptr);
 
            // only reset if still active and periodic
            if (tmr->m_active && (tmr->m_period != 0U))
            {
                STK_ASSERT(tmr->GetHead() == &m_active);
 
                tmr->m_deadline = cmd.timestamp + static_cast<Ticks>(tmr->m_period);
                tmr->m_pending  = false;
 
                next_sleep = NO_WAIT;
            }
            
        break; }
 
        case TimerCommand::CMD_RESTART:
        {
            // atomic stop + re-start: no precondition on current timer state
            Timer *const tmr = cmd.timer;
            STK_ASSERT(tmr != nullptr);
 
            // unlink if currently in the active list
            if (tmr->IsLinked())
            {
                m_active.Unlink(tmr);
            }
 
            // re-arm with fresh parameters
            tmr->m_deadline = cmd.timestamp + static_cast<Ticks>(cmd.delay);
            tmr->m_period   = cmd.period;
            tmr->m_active   = true;
            tmr->m_pending  = false;
            tmr->m_rearming = false;
 
            // re-link to the back of the list
            m_active.LinkBack(tmr);
            next_sleep = NO_WAIT;
            
        break; }
 
        case TimerCommand::CMD_START_OR_RESET:
        {
            Timer *const tmr = cmd.timer;
            STK_ASSERT(tmr != nullptr);
 
            // not currently active: start with supplied parameters
            if (!tmr->m_active)
            {
                STK_ASSERT(!tmr->IsLinked());
 
                tmr->m_deadline = cmd.timestamp + static_cast<Ticks>(cmd.delay);
                tmr->m_period   = cmd.period;
                tmr->m_active   = true;
                tmr->m_pending  = false;
                tmr->m_rearming = false;
 
                m_active.LinkBack(tmr);
            }
            // active and periodic: reset deadline anchored to call-site timestamp
            else if (tmr->m_period != 0U)
            {
                STK_ASSERT(tmr->GetHead() == &m_active);
 
                tmr->m_deadline = cmd.timestamp + static_cast<Ticks>(tmr->m_period);
                tmr->m_pending  = false;
            }
            else
            {
                // noop
            }
 
            // active one-shot: no action - cannot reset a one-shot mid-flight,
            // caller should use Restart() if unconditional re-arm is needed
 
            next_sleep = NO_WAIT;
            
        break; }
 
        case TimerCommand::CMD_SET_PERIOD:
        {
            Timer *const tmr = cmd.timer;
            STK_ASSERT(tmr != nullptr);
            STK_ASSERT(cmd.period != 0U);
 
            // guard: only apply if still active and periodic
            if (tmr->m_active && (tmr->m_period != 0U))
            {
                STK_ASSERT(tmr->GetHead() == &m_active);
 
                // new period takes effect on the next reload, current deadline is
                // intentionally left unchanged so the in-flight interval is not
                // truncated or extended, caller can follow up with Reset() if
                // immediate application is required
                tmr->m_period = cmd.period;
            }
            
        break; }
 
        case TimerCommand::CMD_SHUTDOWN:
        {
            // wake all handler tasks with shutdown sentinels
            for (size_t i = 0U; i < STK_TIMER_THREADS_COUNT; ++i)
            {
                STK_UNUSED(m_queue.Write(nullptr, NO_WAIT));
            }
 
            // signal UpdateTime() to exit its loop
            working = false;
            
        break; }
 
        default:
        {
            STK_ASSERT(false);
            
            break; }
        }
    }
 
    return working;
}

Referenced by UpdateTime().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ProcessTimers()

void stk::time::TimerHost::ProcessTimers ( )

inlineprivate

Handler task body: dequeues expired timers and invokes their OnExpired() callbacks.

Note: Runs in each handler task context. Loops until a nullptr sentinel is dequeued.

Definition at line 780 of file stk_time_timer.h.

{
    Timer *tmr = nullptr;
    bool keep_running = true;
 
    while (keep_running)
    {
        if (!m_queue.Read(tmr))
        {
            break; // no pending timers available
        }
      
        // nullptr is the shutdown sentinel pushed by CMD_SHUTDOWN
        if (tmr == nullptr)
        {
            keep_running = false;
        }
        else if (tmr->m_pending)
        {
            tmr->m_pending = false;
            tmr->OnExpired(this);
        }
        else
        {
            // noop
        }
    }
}

References stk::time::TimerHost::Timer::m_pending, m_queue, and stk::time::TimerHost::Timer::OnExpired().

Referenced by Initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ PushCommand()

bool stk::time::TimerHost::PushCommand ( TimerCommand cmd )

inlineprivate

Enqueue a command for the tick task.

Parameters

[in] cmd Fully initialized TimerCommand to push.

Returns: True on success, false if the command queue is full.

Note: May be called from any task context. On queue-full the assertion fires in debug builds; in release the caller receives false and may retry or escalate.

Definition at line 999 of file stk_time_timer.h.

{
    bool success = true;
    bool proceed_to_write = true;
 
    const bool is_rearm = (cmd.cmd == TimerCommand::CMD_RESTART) ||
                          (cmd.cmd == TimerCommand::CMD_START_OR_RESET);
 
    // rearm coalescing (CMD_RESTART and CMD_START_OR_RESET only)
    if (is_rearm && (cmd.timer != nullptr))
    {
        if (cmd.timer->m_rearming)
        {
            // already rearming - successfully coalesced, no need to write to queue
            proceed_to_write = false;
        }
        else
        {
            cmd.timer->m_rearming = true;
 
            // prevent compiler from sinking the flag write past Write()
            __stk_full_memfence();
        }
    }
 
    // write to command queue
    if (proceed_to_write)
    {
        if (!m_commands.Write(cmd, NO_WAIT))
        {
            // revert the flag if this was a failed rearm attempt
            if (is_rearm && (cmd.timer != nullptr))
            {
                cmd.timer->m_rearming = false;
            }
 
            // queue full: this indicates a usage error - more commands are being
            // issued than the tick task can drain (recoverable in
            // release, caller receives false and can retry or escalate)
            STK_ASSERT(false);
            success = false;
        }
    }
    
    return success;
}

References stk::time::TimerHost::TimerCommand::cmd, stk::time::TimerHost::TimerCommand::CMD_RESTART, stk::time::TimerHost::TimerCommand::CMD_START_OR_RESET, m_commands, stk::time::TimerHost::Timer::m_rearming, stk::NO_WAIT, STK_ASSERT, and stk::time::TimerHost::TimerCommand::timer.

Referenced by Reset(), Restart(), SetPeriod(), Shutdown(), Start(), StartOrReset(), and Stop().

Here is the caller graph for this function:

◆ Reset()

bool stk::time::TimerHost::Reset ( Timer & tmr )

inline

Reset periodic timer's deadline.

Parameters

[in] tmr Timer instance. Must be active and periodic.

Returns: True on success, false if timer is not active, not periodic, or command queue is full.

Definition at line 582 of file stk_time_timer.h.

{
    bool success;
  
    // timer must be active and periodic
    if (tmr.m_active && (tmr.m_period != 0U))
    {
        success = PushCommand({
            .cmd       = TimerCommand::CMD_RESET,
            .timer     = &tmr,
            .timestamp = GetTicks(),
            .delay     = 0U,
            .period    = 0U
        });
    }
    else
    {
        success = false;
    }
 
    return success;
}

References stk::time::TimerHost::TimerCommand::CMD_RESET, stk::GetTicks(), stk::time::TimerHost::Timer::m_active, stk::time::TimerHost::Timer::m_period, and PushCommand().

Referenced by stk_timer_reset().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Restart()

bool stk::time::TimerHost::Restart	(	Timer &	tmr,
		uint32_t	delay,
		uint32_t	period = 0 )

inline

Atomically stop and re-start timer.

Parameters

[in]	tmr	Timer instance (active or inactive).
[in]	delay	Initial delay in ticks before first expiration.
[in]	period	Reload period in ticks (0 is one-shot timer).

Returns: True on success, false if command queue is full.

Note: Unlike calling Stop() followed by Start(), this operation is atomic with respect to the tick task: the timer cannot fire between the implicit stop and re-start, and only one command queue slot is consumed. Useful for watchdog refresh and debounce reset patterns. Safe to call regardless of whether the timer is currently active.

Definition at line 609 of file stk_time_timer.h.

{
    STK_ASSERT(delay <= static_cast<uint32_t>(WAIT_INFINITE));
    STK_ASSERT((period == 0U) || (period <= static_cast<uint32_t>(WAIT_INFINITE)));
 
    return PushCommand({
        .cmd       = TimerCommand::CMD_RESTART,
        .timer     = &tmr,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}

References stk::time::TimerHost::TimerCommand::CMD_RESTART, stk::GetTicks(), PushCommand(), STK_ASSERT, and stk::WAIT_INFINITE.

Referenced by stk_timer_restart().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetPeriod()

bool stk::time::TimerHost::SetPeriod	(	Timer &	tmr,
		uint32_t	period )

inline

Change the period of a running periodic timer without affecting its current deadline.

Parameters

[in]	tmr	Timer instance. Must be active and periodic.
[in]	period	New reload period in ticks. Must be non-zero.

Returns: True on success, false if timer is not active, not periodic, period is zero, or command queue is full.

Note: The new period takes effect on the next reload after the current deadline fires. To apply the new period immediately (restart from now), call Reset() after SetPeriod().

Definition at line 645 of file stk_time_timer.h.

{
    bool success;
  
    // period == 0 is rejected: it would silently convert a periodic timer
    // to one-shot semantics, which is better expressed via Stop() + Start()
    if (tmr.m_active && (tmr.m_period != 0U) && (period != 0U) &&
        (period <= static_cast<uint32_t>(WAIT_INFINITE)))
    {
        success = PushCommand({
            .cmd       = TimerCommand::CMD_SET_PERIOD,
            .timer     = &tmr,
            .timestamp = 0,
            .delay     = 0U,
            .period    = period
        });
    }
    else
    {
        success = false;
    }
 
    return success;
}

References stk::time::TimerHost::TimerCommand::CMD_SET_PERIOD, stk::time::TimerHost::Timer::m_active, stk::time::TimerHost::Timer::m_period, PushCommand(), and stk::WAIT_INFINITE.

Referenced by stk_timer_set_period().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Shutdown()

bool stk::time::TimerHost::Shutdown ( )

inline

Shutdown host instance. All timers are stopped and removed from the host.

Returns: True on success, false if command queue is full.

Definition at line 674 of file stk_time_timer.h.

{
    return PushCommand({
        .cmd       = TimerCommand::CMD_SHUTDOWN,
        .timer     = nullptr,
        .timestamp = 0,
        .delay     = 0U,
        .period    = 0U
    });
}

References stk::time::TimerHost::TimerCommand::CMD_SHUTDOWN, and PushCommand().

Referenced by stk_timerhost_shutdown().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Start()

bool stk::time::TimerHost::Start	(	Timer &	tmr,
		uint32_t	delay,
		uint32_t	period = 0 )

inline

Start timer.

Parameters

[in]	tmr	Timer instance. Must not already be active.
[in]	delay	Initial delay in ticks before first expiration.
[in]	period	Reload period in ticks (0 is one-shot timer).

Returns: True on success, false if timer is already active or command queue is full.

Definition at line 523 of file stk_time_timer.h.

{
    STK_ASSERT(delay <= static_cast<uint32_t>(WAIT_INFINITE));
    STK_ASSERT((period == 0U) || (period <= static_cast<uint32_t>(WAIT_INFINITE)));
    
    bool success;
 
    // timer must not already be active
    if (!tmr.m_active)
    {
        success = PushCommand({
            .cmd       = TimerCommand::CMD_START,
            .timer     = &tmr,
            .timestamp = GetTicks(),
            .delay     = delay,
            .period    = period
        });
    }
    else
    {
        // duplicate attempt to start already started timer is not an error (ignore)
        success = true;
    }
 
    return success;
}

References stk::time::TimerHost::TimerCommand::CMD_START, stk::GetTicks(), stk::time::TimerHost::Timer::m_active, PushCommand(), STK_ASSERT, and stk::WAIT_INFINITE.

Referenced by stk_timer_start().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ StartOrReset()

bool stk::time::TimerHost::StartOrReset	(	Timer &	tmr,
		uint32_t	delay,
		uint32_t	period = 0 )

inline

Start timer if inactive, or reset its deadline if already active and periodic.

Parameters

[in]	tmr	Timer instance (active or inactive).
[in]	delay	Initial delay in ticks (used only when starting).
[in]	period	Reload period in ticks (used only when starting, 0 is one-shot).

Returns: True on success, false if command queue is full.

Note: Collapses the common pattern: if (timer.IsActive()) host.Reset(timer); else host.Start(timer, delay, period); into a single atomic operation, eliminating the TOCTOU race between the IsActive() check and the subsequent call. If the timer is active but one-shot, no action is taken (a one-shot timer mid-flight cannot be reset; use Restart() instead).

Definition at line 627 of file stk_time_timer.h.

{
    STK_ASSERT(delay <= static_cast<uint32_t>(WAIT_INFINITE));
    STK_ASSERT((period == 0U) || (period <= static_cast<uint32_t>(WAIT_INFINITE)));
 
    return PushCommand({
        .cmd       = TimerCommand::CMD_START_OR_RESET,
        .timer     = &tmr,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}

References stk::time::TimerHost::TimerCommand::CMD_START_OR_RESET, stk::GetTicks(), PushCommand(), STK_ASSERT, and stk::WAIT_INFINITE.

Referenced by stk_timer_start_or_reset().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ STK_NONCOPYABLE_CLASS()

stk::time::TimerHost::STK_NONCOPYABLE_CLASS ( TimerHost )

private

References TimerHost().

Here is the call graph for this function:

◆ Stop()

bool stk::time::TimerHost::Stop ( Timer & tmr )

inline

Stop running timer.

Parameters

[in] tmr Timer instance. Must be active.

Returns: True on success, false if timer is not active or command queue is full.

Definition at line 554 of file stk_time_timer.h.

{
    bool success;
  
    // timer must be active
    if (tmr.m_active)
    {
        success = PushCommand({
            .cmd       = TimerCommand::CMD_STOP,
            .timer     = &tmr,
            .timestamp = 0,
            .delay     = 0U,
            .period    = 0U
        });
    }
    else
    {
        // duplicate attempt to stop already stopped timer is not an error (ignore)
        success = true;
    }
 
    return success;
}

References stk::time::TimerHost::TimerCommand::CMD_STOP, stk::time::TimerHost::Timer::m_active, and PushCommand().

Referenced by FrtosPendDrainer::OnExpired(), and stk_timer_stop().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpdateTime()

void stk::time::TimerHost::UpdateTime ( )

inlineprivate

Tick task body: drives the timer list and dispatches expired timers.

Note: Runs exclusively in the tick task context. Loops until CMD_SHUTDOWN is received.

Definition at line 689 of file stk_time_timer.h.

{
    Timeout next_sleep = NO_WAIT;
 
    while (ProcessCommands(next_sleep))
    {
        next_sleep = WAIT_INFINITE;
        const Ticks now = GetTicks();
 
        // using WriteVolatile64() to guarantee correct lockless reading order by ReadVolatile64
        hw::WriteVolatile64(&m_now, now);
 
        Timer *tmr = util::DListCast::ListEntryToParent<Timer>(m_active.GetFirst());
        while (tmr != nullptr)
        {
          Timer *const next = util::DListCast::ListEntryToParent<Timer>(tmr->GetNext());
 
            if (tmr->m_active)
            {
                // check if still pending to be handled
                if (!tmr->m_pending)
                {
                    bool one_shot = false;
                    const Ticks diff = now - tmr->m_deadline;
 
                    if (diff >= 0)
                    {
                        // set timestamp at which timer expired
                        tmr->m_timestamp = now;
 
                        // avoid updating timer again before it was handled
                        tmr->m_pending = true;
 
                        // periodic
                        if (tmr->m_period != 0U)
                        {
                            // reload (use now to avoid drift accumulation)
                            tmr->m_deadline = now + static_cast<Ticks>(tmr->m_period) - diff;
                        }
                        // one-shot
                        else
                        {
                            one_shot = true;
 
                            // remove from active timers
                            m_active.Unlink(tmr);
 
                            // mark as inactive (must follow Unlink)
                            tmr->m_active = false;
                        }
 
                        __stk_full_memfence();
 
                        // push to the handling queue
                        STK_UNUSED(m_queue.Write(tmr));
                    }
 
                    // one-shot timer does not affect next_sleep
                    if (!one_shot)
                    {
                        const Timeout next_deadline = static_cast<Timeout>(tmr->m_deadline - now);
                        STK_ASSERT(next_deadline > 0);
 
                        if ((next_deadline > 0) && (next_deadline < next_sleep))
                        {
                            next_sleep = next_deadline;
                        }
                    }
                }
            }
            else
            {
                // could be stopped externally, remove from active timers
                m_active.Unlink(tmr);
            }
 
            tmr = next;
        }
    }
 
    // unlink all timers on shutdown
    while (Timer::DLEntryType *const tmr = m_active.GetFirst())
    {
        m_active.Unlink(tmr);
    }
}

References stk::util::DListEntry< T, TClosedLoop >::GetNext(), stk::GetTicks(), stk::util::DListCast::ListEntryToParent(), m_active, stk::time::TimerHost::Timer::m_active, stk::time::TimerHost::Timer::m_deadline, m_now, stk::time::TimerHost::Timer::m_pending, stk::time::TimerHost::Timer::m_period, m_queue, stk::time::TimerHost::Timer::m_timestamp, stk::NO_WAIT, ProcessCommands(), STK_ASSERT, STK_UNUSED, stk::WAIT_INFINITE, and stk::hw::WriteVolatile64().

Referenced by Initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ m_active

util::DListHead<Timer, false> stk::time::TimerHost::m_active

private

active timers (tick task only)

Definition at line 467 of file stk_time_timer.h.

Referenced by GetSize(), IsEmpty(), ProcessCommands(), TimerHost(), and UpdateTime().

◆ m_commands

CommandQueue stk::time::TimerHost::m_commands

private

command queue

Definition at line 469 of file stk_time_timer.h.

Referenced by ProcessCommands(), and PushCommand().

◆ m_now

Ticks stk::time::TimerHost::m_now

private

last known current time (ticks)

Definition at line 470 of file stk_time_timer.h.

Referenced by GetTimeNow(), TimerHost(), and UpdateTime().

◆ m_queue

ReadyQueue stk::time::TimerHost::m_queue

private

queue of timers ready for handling

Definition at line 468 of file stk_time_timer.h.

Referenced by ProcessCommands(), ProcessTimers(), and UpdateTime().

◆ m_task_handler_memory

TimerHostMemory stk::time::TimerHost::m_task_handler_memory[1U]

private

handler task memory

Definition at line 464 of file stk_time_timer.h.

Referenced by Initialize(), and TimerHost().

◆ m_task_process

TimerWorkerTask stk::time::TimerHost::m_task_process[1U]

private

handler tasks

Definition at line 466 of file stk_time_timer.h.

Referenced by Initialize(), and TimerHost().

◆ m_task_tick

TimerWorkerTask stk::time::TimerHost::m_task_tick

private

timer task

Definition at line 465 of file stk_time_timer.h.

Referenced by Initialize(), and TimerHost().

◆ m_task_tick_memory

TaskTickMemory stk::time::TimerHost::m_task_tick_memory

private

tick task memory

Definition at line 463 of file stk_time_timer.h.

Referenced by Initialize(), and TimerHost().

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

stk_time_timer.h

Classes

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ CommandQueue

◆ ReadyQueue

◆ TaskTickMemory

◆ TimerFuncType

◆ TimerHostMemory

Member Enumeration Documentation

◆ EConsts

Constructor & Destructor Documentation

◆ TimerHost()

◆ ~TimerHost()

Member Function Documentation

◆ GetSize()

◆ GetTimeNow()

◆ Initialize()

◆ IsEmpty()

◆ ProcessCommands()

◆ ProcessTimers()

◆ PushCommand()

◆ Reset()

◆ Restart()

◆ SetPeriod()

◆ Shutdown()

◆ Start()

◆ StartOrReset()

◆ STK_NONCOPYABLE_CLASS()

◆ Stop()

◆ UpdateTime()

Member Data Documentation

◆ m_active

◆ m_commands

◆ m_now

◆ m_queue

◆ m_task_handler_memory

◆ m_task_process

◆ m_task_tick

◆ m_task_tick_memory