stk_time_timer.h

Go to the documentation of this file.

/*
 * SuperTinyKernel(TM) RTOS: 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 1U
#endif

#ifndef STK_TIMER_HANDLER_STACK_SIZE
    #define STK_TIMER_HANDLER_STACK_SIZE 256U
#endif

#ifndef STK_TIMER_COUNT_MAX
    #define STK_TIMER_COUNT_MAX 32U
#endif

class TimerHost
{
public:
    enum EConsts : size_t
    {
        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)
    };

    class Timer : private util::DListEntry<Timer, false>
    {
        friend class TimerHost;
        friend class util::DListCast; // allow casts because DListEntry is private
 
    public:
        explicit Timer() 
            : m_deadline(0), m_timestamp(0), m_period(0U), m_active(false), 
              m_pending(false), m_rearming(false)
        {}

        STK_VIRT_DTOR ~Timer() = default;
        
        enum { DLEntryTag = 1 };

        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 GetRemainingTicks() const;
 
    private:
        STK_NONCOPYABLE_CLASS(Timer);
 
        Ticks         m_deadline;  
        Ticks         m_timestamp; 
        uint32_t      m_period;    
        volatile bool m_active;    
        volatile bool m_pending;   
        volatile bool m_rearming;  
    };

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

    ~TimerHost() = default;

    void Initialize(IKernel *kernel, EAccessMode mode);

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

    bool Stop(Timer &tmr);

    bool Reset(Timer &tmr);

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

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

    bool SetPeriod(Timer &tmr, 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(0U), 
              m_mode(ACCESS_USER), m_weight(DEFAULT_WEIGHT)
        {}
 
        // ITask
        EAccessMode GetAccessMode() const override { return m_mode; }
        void OnDeadlineMissed(uint32_t)   override {}
        void OnExit()                     override {}
        int32_t GetWeight()         const override { return m_weight; }
        const char *GetTraceName()  const override { return nullptr; }
 
        // IStackMemory
        const Word *GetStack()      const override { return m_stack; }
        size_t GetStackSize()       const override { return m_stack_size; }
        size_t GetStackSizeBytes()  const override { return (m_stack_size * sizeof(Word)); }

        void Initialize(TimerHost *host, Word *stack, size_t stack_size, EAccessMode mode, 
                        TimerFuncType const func)
        {
            m_host       = host;
            m_func       = func;
            m_stack      = stack;
            m_stack_size = stack_size;
            m_mode       = mode;
            m_weight     = DEFAULT_WEIGHT;
        }

        void SetWeight(int32_t weight) { m_weight = weight; }
 
    private:
        void Run() override { 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::PipeT<Timer *, STK_TIMER_COUNT_MAX>      ReadyQueue;

    typedef sync::PipeT<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::GetRemainingTicks
// ---------------------------------------------------------------------------
 
inline uint32_t TimerHost::Timer::GetRemainingTicks() const
{
    uint32_t remaining_ticks = 0U;
 
    if (m_active)
    {
        // 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
        const Ticks remaining = m_deadline - GetTicks();
        
        if (remaining > 0)
        {
            remaining_ticks = static_cast<uint32_t>(remaining);
        }
    }
 
    return remaining_ticks;
}
 
// ---------------------------------------------------------------------------
// Initialize
// ---------------------------------------------------------------------------
 
inline void TimerHost::Initialize(IKernel *kernel, EAccessMode mode)
{
    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);
}
 
// ---------------------------------------------------------------------------
// Start
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Start(Timer &tmr, 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)));
    
    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;
}
 
// ---------------------------------------------------------------------------
// Stop
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Stop(Timer &tmr)
{
    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;
}
 
// ---------------------------------------------------------------------------
// Reset
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Reset(Timer &tmr)
{
    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;
}
 
// ---------------------------------------------------------------------------
// Restart
// ---------------------------------------------------------------------------
 
inline bool TimerHost::Restart(Timer &tmr, 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     = &tmr,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}
 
// ---------------------------------------------------------------------------
// StartOrReset
// ---------------------------------------------------------------------------
 
inline bool TimerHost::StartOrReset(Timer &tmr, 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     = &tmr,
        .timestamp = GetTicks(),
        .delay     = delay,
        .period    = period
    });
}
 
// ---------------------------------------------------------------------------
// SetPeriod
// ---------------------------------------------------------------------------
 
inline bool TimerHost::SetPeriod(Timer &tmr, uint32_t period)
{
    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;
}
 
// ---------------------------------------------------------------------------
// 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;
        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);
    }
}
 
// ---------------------------------------------------------------------------
// ProcessTimers  (handler task body)
// ---------------------------------------------------------------------------
 
inline void TimerHost::ProcessTimers()
{
    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
        }
    }
}
 
// ---------------------------------------------------------------------------
// ProcessCommands  (tick task only)
// ---------------------------------------------------------------------------
 
inline bool TimerHost::ProcessCommands(Timeout next_sleep)
{
    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;
}
 
// ---------------------------------------------------------------------------
// PushCommand
// ---------------------------------------------------------------------------
 
inline bool TimerHost::PushCommand(TimerCommand cmd)
{
    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;
}
 
} // namespace time
} // namespace stk
 
#endif /* STK_TIME_TIMER_H_ */