stk_time_timer.h

Go to the documentation of this file.

/*
 * SuperTinyKernel™ (STK): Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
 *
 * Source: https://github.com/SuperTinyKernel-RTOS
 *
 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
 * License: MIT License, see LICENSE for a full text.
 */
 
#ifndef STK_TIME_TIMER_H_
#define STK_TIME_TIMER_H_
 
#include "sync/stk_sync_event.h"
#include "sync/stk_sync_pipe.h"

 
namespace stk {
namespace time {

#ifndef STK_TIMER_THREADS_COUNT
    #define STK_TIMER_THREADS_COUNT 1
#endif

#ifndef STK_TIMER_HANDLER_STACK_SIZE
    #define STK_TIMER_HANDLER_STACK_SIZE 256
#endif

#ifndef STK_TIMER_COUNT_MAX
    #define STK_TIMER_COUNT_MAX 32
#endif

class TimerHost
{
public:
    enum EConsts
    {
        TASK_COUNT = (1 + STK_TIMER_THREADS_COUNT),

        TASK_TICK_MEMORY_SIZE = stk::Max<size_t>(256U, STK_STACK_SIZE_MIN),

        TASK_HANDLER_STACK_SIZE = stk::Max<size_t>(STK_TIMER_HANDLER_STACK_SIZE, STK_STACK_SIZE_MIN)
    };

    class Timer : private util::DListEntry<Timer, false>
    {
        friend class TimerHost;
 
    public:
        Timer() : m_deadline(0), m_timestamp(0), m_period(0), m_active(false), m_pending(false)
        {}

        ~Timer()
        {}
 
        virtual void OnExpired(TimerHost *host) = 0;
 
        bool IsActive() const      { return m_active; }
        Ticks GetDeadline() const  { return m_deadline; }
        Ticks GetTimestamp() const { return m_timestamp; }
        uint32_t GetPeriod() const { return m_period; }

        uint32_t GetRemainingTime() const;
 
    private:
        STK_NONCOPYABLE_CLASS(Timer);
 
        Ticks         m_deadline;  
        Ticks         m_timestamp; 
        uint32_t      m_period;    
        volatile bool m_active;    
        volatile bool m_pending;   
    };
 
    explicit TimerHost()
        : m_task_tick_memory(), m_task_handler_memory(), m_task_tick(), m_task_process(), m_active(), m_now(0)
    {}

    ~TimerHost()
    {}

    void Initialize(IKernel *kernel, EAccessMode mode);

    bool Start(Timer &timer, uint32_t delay, uint32_t period = 0);

    bool Stop(Timer &timer);

    bool Reset(Timer &timer);

    bool Restart(Timer &timer, uint32_t delay, uint32_t period = 0);

    bool StartOrReset(Timer &timer, uint32_t delay, uint32_t period = 0);

    bool SetPeriod(Timer &timer, uint32_t period);

    bool IsEmpty() const { return m_active.IsEmpty(); }

    size_t GetSize() const { return m_active.GetSize(); }

    bool Shutdown();

    Ticks GetTimeNow() const { return hw::ReadVolatile64(&m_now); }
 
private:
    STK_NONCOPYABLE_CLASS(TimerHost);

    typedef void (*TimerFuncType) (TimerHost *host);

    class TimerWorkerTask : public ITask
    {
    public:
        explicit TimerWorkerTask()
            : m_func(nullptr), m_host(nullptr), m_stack(nullptr), m_stack_size(0), m_mode(ACCESS_USER), m_weight(0)
        {}
 
        // ITask
        EAccessMode GetAccessMode() const { return m_mode; }
        void OnDeadlineMissed(uint32_t duration) { (void)duration; }
        int32_t GetWeight() const         { return m_weight; }
        TId GetId() const                 { return hw::PtrToWord(this); }
        const char *GetTraceName() const  { return nullptr; }
 
        // IStackMemory
        Word *GetStack() const           { return m_stack; }
        size_t GetStackSize() const      { return m_stack_size; }
        size_t GetStackSizeBytes() const { return m_stack_size * sizeof(Word); }
 
        void Initialize(TimerHost *host, Word *stack, size_t stack_size, EAccessMode mode, TimerFuncType func)
        {
            m_host       = host;
            m_func       = func;
            m_stack      = stack;
            m_stack_size = stack_size;
            m_mode       = mode;
            m_weight     = 1;
        }
 
        void SetWeight(int32_t weight) { m_weight = weight; }
 
    private:
        void Run() { m_func(m_host); }
 
        TimerFuncType m_func;
        TimerHost    *m_host;
        Word         *m_stack;
        size_t        m_stack_size;
        EAccessMode   m_mode;
        int32_t       m_weight;
    };
 
    struct TimerCommand
    {
        enum EId : uint8_t
        {
            CMD_SHUTDOWN = 0,   
            CMD_START,          
            CMD_STOP,           
            CMD_RESET,          
            CMD_RESTART,        
            CMD_START_OR_RESET, 
            CMD_SET_PERIOD      
        };
 
        EId      cmd;       
        Timer   *timer;     
        Ticks    timestamp; 
        uint32_t delay;     
        uint32_t period;    
    };
 
    void UpdateTime();
    void ProcessTimers();
    bool ProcessCommands(Timeout next_sleep);
    bool PushCommand(TimerCommand cmd);
 
    typedef StackMemoryDef<TASK_TICK_MEMORY_SIZE>::Type   TaskTickMemory;
    typedef StackMemoryDef<TASK_HANDLER_STACK_SIZE>::Type TimerHostMemory;
    typedef sync::Pipe<Timer *, STK_TIMER_COUNT_MAX>      ReadyQueue;
    typedef sync::Pipe<TimerCommand, STK_TIMER_COUNT_MAX> CommandQueue;
 
    TaskTickMemory                m_task_tick_memory;                             
    TimerHostMemory               m_task_handler_memory[STK_TIMER_THREADS_COUNT]; 
    TimerWorkerTask               m_task_tick;                                    
    TimerWorkerTask               m_task_process[STK_TIMER_THREADS_COUNT];        
    util::DListHead<Timer, false> m_active;                                       
    ReadyQueue                    m_queue;                                        
    CommandQueue                  m_commands;                                     
    Ticks                         m_now;                                          
};
 
// ---------------------------------------------------------------------------
// Timer::GetTimeRemaining
// ---------------------------------------------------------------------------
 
inline uint32_t TimerHost::Timer::GetRemainingTime() const
{
    if (!m_active)
        return 0;
 
    // if deadline has passed but not yet been processed by the tick task,
    // remaining would be negative, result fits in uint32_t because delay and
    // period are uint32_t, so remaining time is bounded by uint32_t max
    Ticks remaining = m_deadline - GetTicks();
    return (remaining > 0 ? static_cast<uint32_t>(remaining) : 0);
}
 
// ---------------------------------------------------------------------------
// Initialize
// ---------------------------------------------------------------------------
 
inline void TimerHost::Initialize(IKernel *kernel, EAccessMode mode)
{
    for (int32_t i = 0; 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);
}
 
// ---------------------------------------------------------------------------
// Start
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Start(Timer &timer, uint32_t delay, uint32_t period)
{
    STK_ASSERT(delay <= static_cast<uint32_t>(WAIT_INFINITE));
    STK_ASSERT((period == 0U) || (period <= static_cast<uint32_t>(WAIT_INFINITE)));
 
    // timer must not already be active
    if (timer.m_active)
        return false;
 
    return PushCommand({
        .cmd       = TimerCommand::CMD_START,
        .timer     = &timer,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}
 
// ---------------------------------------------------------------------------
// Stop
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Stop(Timer &timer)
{
    // timer must be active
    if (!timer.m_active)
        return false;
 
    return PushCommand({
        .cmd       = TimerCommand::CMD_STOP,
        .timer     = &timer,
        .timestamp = 0,
        .delay     = 0U,
        .period    = 0U
    });
}
 
// ---------------------------------------------------------------------------
// Reset
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Reset(Timer &timer)
{
    // timer must be active and periodic
    if (!timer.m_active || (timer.m_period == 0))
        return false;
 
    return PushCommand({
        .cmd      = TimerCommand::CMD_RESET,
        .timer     = &timer,
        .timestamp = GetTicks(),
        .delay     = 0U,
        .period    = 0U
    });
}
 
// ---------------------------------------------------------------------------
// Restart
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Restart(Timer &timer, uint32_t delay, uint32_t period)
{
    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     = &timer,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}
 
// ---------------------------------------------------------------------------
// StartOrReset
// ---------------------------------------------------------------------------
 
inline bool TimerHost::StartOrReset(Timer &timer, uint32_t delay, uint32_t period)
{
    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     = &timer,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}
 
// ---------------------------------------------------------------------------
// SetPeriod
// ---------------------------------------------------------------------------
 
inline bool TimerHost::SetPeriod(Timer &timer, uint32_t period)
{
    // period == 0 is rejected: it would silently convert a periodic timer
    // to one-shot semantics, which is better expressed via Stop() + Start()
    if (!timer.m_active || (timer.m_period == 0U) || (period == 0U) ||
        (period > static_cast<uint32_t>(WAIT_INFINITE)))
    {
        return false;
    }
 
    return PushCommand({
        .cmd       = TimerCommand::CMD_SET_PERIOD,
        .timer     = &timer,
        .timestamp = 0,
        .delay     = 0U,
        .period    = period
    });
}
 
// ---------------------------------------------------------------------------
// Shutdown
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Shutdown()
{
    return PushCommand({
        .cmd       = TimerCommand::CMD_SHUTDOWN,
        .timer     = nullptr,
        .timestamp = 0,
        .delay     = 0U,
        .period    = 0U
    });
}
 
// ---------------------------------------------------------------------------
// UpdateTime  (tick task body)
// ---------------------------------------------------------------------------
 
inline void TimerHost::UpdateTime()
{
    Timeout next_sleep = NO_WAIT;
 
    while (ProcessCommands(next_sleep))
    {
        next_sleep = WAIT_INFINITE;
 
        Ticks now = GetTicks();
 
        // using WriteVolatile64() to guarantee correct lockless reading order by ReadVolatile64
        hw::WriteVolatile64(&m_now, now);
 
        Timer *timer = static_cast<Timer *>(m_active.GetFirst());
        while (timer != nullptr)
        {
            Timer *next = static_cast<Timer *>(timer->GetNext());
 
            if (timer->m_active)
            {
                // check if still pending to be handled
                if (timer->m_pending)
                {
                    timer = next;
                    continue;
                }
 
                bool one_shot = false;
                Ticks diff = now - timer->m_deadline;
 
                if (diff >= 0)
                {
                    // set timestamp at which timer expired
                    timer->m_timestamp = now;
 
                    // avoid updating timer again before it was handled
                    timer->m_pending = true;
 
                    // periodic
                    if (timer->m_period != 0)
                    {
                        // reload (use now to avoid drift accumulation)
                        timer->m_deadline = now + static_cast<Ticks>(timer->m_period) - diff;
                    }
                    // one-shot
                    else
                    {
                        one_shot = true;
 
                        // remove from active timers
                        m_active.Unlink(timer);
 
                        // mark as inactive (must follow Unlink)
                        timer->m_active = false;
                    }
 
                    __stk_full_memfence();
 
                    // push to the handling queue
                    m_queue.Write(timer);
                }
 
                // one-shot timer does not affect next_sleep
                if (!one_shot)
                {
                    Timeout next_deadline = static_cast<Timeout>(timer->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(timer);
            }
 
            timer = next;
        }
    }
 
    // unlink all timers on shutdown
    while (Timer::DLEntryType *timer = m_active.GetFirst())
        m_active.Unlink(timer);
}
 
// ---------------------------------------------------------------------------
// ProcessTimers  (handler task body)
// ---------------------------------------------------------------------------
 
inline void TimerHost::ProcessTimers()
{
    Timer *timer;
    while (m_queue.Read(timer))
    {
        // nullptr is the shutdown sentinel pushed by CMD_SHUTDOWN
        if (timer == nullptr)
            break;
 
        if (timer->m_pending)
        {
            timer->m_pending = false;
            timer->OnExpired(this);
        }
    }
}
 
// ---------------------------------------------------------------------------
// ProcessCommands  (tick task only)
// ---------------------------------------------------------------------------
 
inline bool TimerHost::ProcessCommands(Timeout next_sleep)
{
    // if nothing is active, sleep indefinitely until a command arrives
    next_sleep = (m_active.IsEmpty() ? WAIT_INFINITE : next_sleep);
 
    TimerCommand cmd;
    while (m_commands.Read(cmd, next_sleep))
    {
        switch (cmd.cmd)
        {
        case TimerCommand::CMD_START: {
            Timer *timer = cmd.timer;
            STK_ASSERT(timer != nullptr);
 
            // reject if already active or linked (double-start)
            if (timer->m_active)
                continue;
 
            STK_ASSERT(!timer->IsLinked());
 
            timer->m_deadline = cmd.timestamp + cmd.delay;
            timer->m_period   = cmd.period;
            timer->m_active   = true;
            timer->m_pending  = false;
 
            m_active.LinkBack(timer);
            next_sleep = NO_WAIT;
            break; }
 
        case TimerCommand::CMD_STOP: {
            Timer *timer = cmd.timer;
            STK_ASSERT(timer != nullptr);
 
            timer->m_active  = false;
            timer->m_pending = false;
 
            // allow possibly duplicate CMD_STOP as it is harmless for the logic
            if (timer->IsLinked())
                m_active.Unlink(timer);
            break; }
 
        case TimerCommand::CMD_RESET: {
            Timer *timer = cmd.timer;
            STK_ASSERT(timer != nullptr);
 
            // only reset if still active and periodic
            if (!timer->m_active || (timer->m_period == 0))
                continue;
 
            STK_ASSERT(timer->GetHead() == &m_active);
 
            timer->m_deadline = cmd.timestamp + timer->m_period;
            timer->m_pending  = false;
 
            next_sleep = NO_WAIT;
            break; }
 
        case TimerCommand::CMD_RESTART: {
            // atomic stop + re-start: no precondition on current timer state
            Timer *timer = cmd.timer;
            STK_ASSERT(timer != nullptr);
 
            // unlink if currently in the active list
            if (timer->IsLinked())
                m_active.Unlink(timer);
 
            // re-arm with fresh parameters
            timer->m_deadline = cmd.timestamp + cmd.delay;
            timer->m_period   = cmd.period;
            timer->m_active   = true;
            timer->m_pending  = false;
 
            // re-link to the back of the list
            m_active.LinkBack(timer);
            next_sleep = NO_WAIT;
            break; }
 
        case TimerCommand::CMD_START_OR_RESET: {
            Timer *timer = cmd.timer;
            STK_ASSERT(timer != nullptr);
 
            // not currently active: start with supplied parameters
            if (!timer->m_active)
            {
                STK_ASSERT(!timer->IsLinked());
 
                timer->m_deadline = cmd.timestamp + cmd.delay;
                timer->m_period   = cmd.period;
                timer->m_active   = true;
                timer->m_pending  = false;
 
                m_active.LinkBack(timer);
            }
            else
            // active and periodic: reset deadline anchored to call-site timestamp
            if (timer->m_period != 0)
            {
                STK_ASSERT(timer->GetHead() == &m_active);
 
                timer->m_deadline = cmd.timestamp + timer->m_period;
                timer->m_pending  = false;
            }
 
            // 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 *timer = cmd.timer;
            STK_ASSERT(timer != nullptr);
            STK_ASSERT(cmd.period != 0U);
 
            // guard: only apply if still active and periodic
            if (!timer->m_active || (timer->m_period == 0U))
                continue;
 
            STK_ASSERT(timer->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
            timer->m_period = cmd.period;
            break; }
 
        case TimerCommand::CMD_SHUTDOWN: {
            // wake all handler tasks with shutdown sentinels
            for (int32_t i = 0; i < STK_TIMER_THREADS_COUNT; ++i)
                m_queue.Write(nullptr, NO_WAIT);
 
            // signal UpdateTime() to exit its loop
            return false; }
 
        default: {
            STK_ASSERT(false);
            break; }
        }
    }
 
    return true;
}
 
// ---------------------------------------------------------------------------
// PushCommand
// ---------------------------------------------------------------------------
 
inline bool TimerHost::PushCommand(TimerCommand cmd)
{
    if (!m_commands.Write(cmd, NO_WAIT))
    {
        // queue full: this indicates a usage error — more commands are being
        // issued than the tick task can drain. Loud in debug, recoverable in
        // release (caller receives false and can retry or escalate).
        STK_ASSERT(false);
        return false;
    }
 
    return true;
}
 
} // namespace time
} // namespace stk
 
#endif /* STK_TIME_TIMER_H_ */