stk::time::PeriodicTrigger Struct Reference

Lightweight periodic trigger: returns true once per configured period when polled. More...

#include <stk_time_util.h>

Public Member Functions
	PeriodicTrigger (uint32_t period, bool start=false)
	Construct a PeriodicTrigger.
uint32_t	GetPeriod () const
	Get currently configured trigger period.
void	SetPeriod (uint32_t period)
	Change the trigger period while preserving phase.
void	Restart ()
	Reset the trigger and start.
bool	Poll ()
	Check whether the scheduled trigger time has been reached.

Protected Attributes
Ticks	m_next
	Next trigger time in ticks.
uint32_t	m_period
	Trigger period in ticks. Modified only by SetPeriod(). Must be > 0.

Detailed Description

Lightweight periodic trigger: returns true once per configured period when polled.

Implements an absolute-time based periodic trigger. Internally stores the tick value of the next scheduled firing (m_next). Each call to Poll() compares the current tick count against m_next. When the current time reaches or exceeds m_next, Poll() returns true and advances m_next by exactly one period.

Because the next trigger time is incremented by m_period rather than reset to the current time, the long-term firing rate remains stable even if individual Poll() calls are delayed.

Usage example:

// Trigger every 500 ticks (actual wall-clock duration depends on tick resolution).
stk::time::PeriodicTrigger trigger(500, true);
 
// Inside a task loop:
if (trigger.Poll())
{
    // executed once per 500-tick period
}

Note

Not thread-safe. Intended for use within a single task or ISR context.

If constructed without start=true, Restart() must be called before Poll().

When started (either via constructor or Restart()), the first Poll() firing occurs no earlier than m_period ticks after the start moment.

Definition at line 50 of file stk_time_util.h.

Constructor & Destructor Documentation

PeriodicTrigger()

stk::time::PeriodicTrigger::PeriodicTrigger ( uint32_t period, bool start = false )

inline

Construct a PeriodicTrigger.

Parameters

[in]	period	Trigger period in ticks. Must be > 0. The wall-clock duration of one tick is determined by the resolution passed to IKernel::Initialize() (see IKernel::GetTickResolution()).
[in]	start	true to start immediately, false otherwise (default).

Note

If start=true, equivalent to calling Restart() from the constructor. The first Poll() firing will occur no earlier than period ticks after construction.

Definition at line 62 of file stk_time_util.h.

                                                       : m_next(0), m_period(period)
    {
        if (start)
        {
            Restart();
        }
    }

References m_next, m_period, and Restart().

Here is the call graph for this function:

Member Function Documentation

GetPeriod()

uint32_t stk::time::PeriodicTrigger::GetPeriod ( ) const

inline

Get currently configured trigger period.

Returns

Trigger period in ticks.

Definition at line 73 of file stk_time_util.h.

    {
        return m_period;
    }

References m_period.

Referenced by stk_periodic_trigger_get_period().

Here is the caller graph for this function:

Poll()

bool stk::time::PeriodicTrigger::Poll ( )

inline

Check whether the scheduled trigger time has been reached.

Returns

true once when the current tick count reaches or exceeds the scheduled trigger time, false otherwise.

Note

Should be called regularly (e.g. every task iteration). If multiple full periods have elapsed since the previous call, only a single true is returned and m_next is advanced by exactly one period. Subsequent calls will continue to catch up one period at a time until the schedule is realigned.

Warning

Must be started (constructor with start=true or Restart()).

Definition at line 108 of file stk_time_util.h.

    {
        STK_ASSERT(m_next > 0);
 
        bool triggered = false;
        const Ticks diff = GetTicks() - m_next;
 
        if (diff >= 0)
        {
            m_next += static_cast<Ticks>(m_period);
            triggered = true;
        }
 
        return triggered;
    }

References stk::GetTicks(), m_next, m_period, and STK_ASSERT.

Referenced by stk_periodic_trigger_poll().

Here is the call graph for this function:

Here is the caller graph for this function:

Restart()

void stk::time::PeriodicTrigger::Restart ( )

inline

Reset the trigger and start.

Note

Sets m_next to (current ticks + m_period). The next Poll() firing will occur no earlier than m_period ticks after this call.

Definition at line 93 of file stk_time_util.h.

    {
        m_next = GetTicks() + static_cast<Ticks>(m_period);
    }

References stk::GetTicks(), m_next, and m_period.

Referenced by PeriodicTrigger(), and stk_periodic_trigger_restart().

Here is the call graph for this function:

Here is the caller graph for this function:

SetPeriod()

void stk::time::PeriodicTrigger::SetPeriod ( uint32_t period )

inline

Change the trigger period while preserving phase.

Parameters

[in]

period

New trigger period in ticks. Must be > 0.

Note

Adjusts m_next so that the relative progress toward the next firing is preserved. Takes effect immediately.

Definition at line 83 of file stk_time_util.h.

    {
        m_next = (m_next - static_cast<Ticks>(m_period)) + static_cast<Ticks>(period);
        m_period = period;
    }

References m_next, and m_period.

Referenced by stk_periodic_trigger_set_period().

Here is the caller graph for this function:

Member Data Documentation

m_next

Ticks stk::time::PeriodicTrigger::m_next

protected

Next trigger time in ticks.

Definition at line 125 of file stk_time_util.h.

Referenced by PeriodicTrigger(), Poll(), Restart(), and SetPeriod().

m_period

uint32_t stk::time::PeriodicTrigger::m_period

protected

Trigger period in ticks. Modified only by SetPeriod(). Must be > 0.

Definition at line 126 of file stk_time_util.h.

Referenced by GetPeriod(), PeriodicTrigger(), Poll(), Restart(), and SetPeriod().

---

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

• stk_time_util.h