stk::time::TimerHost::Timer Class Reference

Abstract base class for a timer managed by TimerHost. More...

#include <stk_time_timer.h>

Inheritance diagram for stk::time::TimerHost::Timer:

Collaboration diagram for stk::time::TimerHost::Timer:

Public Types
enum	{ DLEntryTag = 1 }
	A tag for type-safe casts done by CastListEntryToParent. More...

Public Member Functions
	Timer ()
	Default constructor.
STK_VIRT_DTOR	~Timer ()=default
	Destructor.
virtual void	OnExpired (TimerHost *host)=0
	Callback invoked by the handler task when this timer expires.
bool	IsActive () const
	Check whether the timer is currently active.
Ticks	GetDeadline () const
	Get the absolute time in ticks at which the timer will expire.
Ticks	GetTimestamp () const
	Get the tick count at which the timer last expired.
uint32_t	GetPeriod () const
	Get the reload period of the timer.
uint32_t	GetRemainingTicks () const
	Get remaining ticks until the timer next expires.

Private Types
enum
	A tag for type-safe casts done by CastListEntryToParent. More...
typedef DListEntry< Timer, TClosedLoop >	DLEntryType
	Convenience alias for this entry type. Used to avoid repeating the full template spelling.
typedef DListHead< Timer, TClosedLoop >	DLHeadType
	Convenience alias for the corresponding list head type.

Private Member Functions
	STK_NONCOPYABLE_CLASS (Timer)
DLHeadType *	GetHead ()
	Get the list head this entry currently belongs to.
DLEntryType *	GetNext ()
	Get the next entry in the list.
DLEntryType *	GetPrev ()
	Get the previous entry in the list.
bool	IsLinked () const
	Check whether this entry is currently a member of any list.
	operator Timer * ()
	Implicit conversion to a mutable pointer to the host object (T).
	operator const Timer * () const
	Implicit conversion to a const pointer to the host object (T).
void	Link (DLHeadType *head, DLEntryType *next, DLEntryType *prev)
	Wire this entry into a list between prev and next.
void	Unlink ()
	Remove this entry from its current list.

Private Attributes
Ticks	m_deadline
	absolute expiration time (ticks)
Ticks	m_timestamp
	absolute time at which timer expired (ticks), updated by TimerHost
uint32_t	m_period
	reload period in ticks (0 = one-shot)
volatile bool	m_active
	true if active
volatile bool	m_pending
	true if pending to be handled
volatile bool	m_rearming
	true while a CMD_RESTART / CMD_START_OR_RESET is already in the command queue
DLHeadType *	m_head
	Owning list head, or NULL when the entry is not linked.
DLEntryType *	m_next
	Next entry in the list, or NULL (open list boundary) / first entry (closed loop).
DLEntryType *	m_prev
	Previous entry in the list, or NULL (open list boundary) / last entry (closed loop).

Friends
class	TimerHost
class	util::DListCast

Detailed Description

Abstract base class for a timer managed by TimerHost.

To implement a concrete timer, inherit from this class and override OnExpired(). The timer instance must outlive the TimerHost or be explicitly stopped before destruction, as TimerHost holds a non-owning pointer to each active timer.

Each Timer instance may be registered with at most one TimerHost at a time.

See also

TimerHost::Start, TimerHost::Stop, TimerHost::Reset, TimerHost::Restart

Definition at line 137 of file stk_time_timer.h.

Member Typedef Documentation

DLEntryType

typedef DListEntry<Timer, TClosedLoop> stk::util::DListEntry< Timer, TClosedLoop >::DLEntryType

inherited

Convenience alias for this entry type. Used to avoid repeating the full template spelling.

Definition at line 75 of file stk_linked_list.h.

DLHeadType

typedef DListHead<Timer, TClosedLoop> stk::util::DListEntry< Timer, TClosedLoop >::DLHeadType

inherited

Convenience alias for the corresponding list head type.

Definition at line 80 of file stk_linked_list.h.

Member Enumeration Documentation

anonymous enum

anonymous enum

A tag for type-safe casts done by CastListEntryToParent.

See also

CastListEntryToParent.

Enumerator
DLEntryTag

Definition at line 158 of file stk_time_timer.h.

{ DLEntryTag = 1 };

anonymous enum

anonymous enum

inherited

A tag for type-safe casts done by CastListEntryToParent.

See also

CastListEntryToParent.

Definition at line 70 of file stk_linked_list.h.

{ DLEntryTag = 1 };

Constructor & Destructor Documentation

Timer()

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

inlineexplicit

Default constructor.

Definition at line 145 of file stk_time_timer.h.

            : m_deadline(0), m_timestamp(0), m_period(0U), m_active(false), 
              m_pending(false), m_rearming(false)
        {}

References m_active, m_deadline, m_pending, m_period, m_rearming, and m_timestamp.

Referenced by STK_NONCOPYABLE_CLASS().

Here is the caller graph for this function:

~Timer()

STK_VIRT_DTOR stk::time::TimerHost::Timer::~Timer ( )

default

Destructor.

Note

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

References STK_VIRT_DTOR.

Member Function Documentation

GetDeadline()

Ticks stk::time::TimerHost::Timer::GetDeadline ( ) const

inline

Get the absolute time in ticks at which the timer will expire.

Returns

Absolute expiration deadline in ticks.

Note

Meaningful only when IsActive() returns true.

Definition at line 180 of file stk_time_timer.h.

{ return m_deadline; }

References m_deadline.

Referenced by stk_timer_get_deadline(), and xTimerGetExpiryTime().

Here is the caller graph for this function:

GetHead()

DLHeadType * stk::util::DListEntry< Timer, TClosedLoop >::GetHead ( )

inlineinherited

Get the list head this entry currently belongs to.

Returns

Pointer to the owning DListHead, or NULL if the entry is not linked.

Definition at line 85 of file stk_linked_list.h.

{ return m_head; }

GetNext()

DLEntryType * stk::util::DListEntry< Timer, TClosedLoop >::GetNext ( )

inlineinherited

Get the next entry in the list.

Returns

Pointer to the next DListEntry, or NULL if this is the last entry (open list) or the first entry (closed loop, where next wraps to first).

Note

In a closed loop (TClosedLoop == true) this pointer is never NULL when the entry is linked.

Definition at line 98 of file stk_linked_list.h.

{ return m_next; }

GetPeriod()

uint32_t stk::time::TimerHost::Timer::GetPeriod ( ) const

inline

Get the reload period of the timer.

Returns

Period in ticks, or 0 for a one-shot timer.

Definition at line 191 of file stk_time_timer.h.

{ return m_period; }

References m_period.

Referenced by stk_timer_get_period().

Here is the caller graph for this function:

GetPrev()

DLEntryType * stk::util::DListEntry< Timer, TClosedLoop >::GetPrev ( )

inlineinherited

Get the previous entry in the list.

Returns

Pointer to the previous DListEntry, or NULL if this is the first entry (open list) or the last entry (closed loop, where prev wraps to last).

Note

In a closed loop (TClosedLoop == true) this pointer is never NULL when the entry is linked.

Definition at line 114 of file stk_linked_list.h.

{ return m_prev; }

GetRemainingTicks()

uint32_t stk::time::TimerHost::Timer::GetRemainingTicks ( ) const

inline

Get remaining ticks until the timer next expires.

Returns

Ticks remaining, or 0 if already expired / not active.

Note

The value is advisory: it is computed from m_now (the last value written by the tick task) and may be up to one tick task wake cycle stale. If the deadline has already passed but not yet been processed, 0 is returned.

Definition at line 477 of file stk_time_timer.h.

{
    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;
}

References stk::GetTicks(), m_active, and m_deadline.

Referenced by stk_timer_get_remaining_ticks().

Here is the call graph for this function:

Here is the caller graph for this function:

GetTimestamp()

Ticks stk::time::TimerHost::Timer::GetTimestamp ( ) const

inline

Get the tick count at which the timer last expired.

Returns

Absolute tick count recorded by the tick task at expiration time, or 0 if the timer has never fired.

Definition at line 186 of file stk_time_timer.h.

{ return m_timestamp; }

References m_timestamp.

Referenced by stk_timer_get_timestamp().

Here is the caller graph for this function:

IsActive()

bool stk::time::TimerHost::Timer::IsActive ( ) const

inline

Check whether the timer is currently active.

Returns

True if the timer has been started and not yet stopped or expired (one-shot).

Note

The value is advisory, it is written by the tick task and read without synchronization, so it may be transiently stale on multi-core targets.

Definition at line 174 of file stk_time_timer.h.

{ return m_active; }

References m_active.

Referenced by osTimerDelete(), osTimerIsRunning(), osTimerStop(), stk_timer_destroy(), stk_timer_is_active(), xTimerDelete(), xTimerGetExpiryTime(), xTimerStop(), and xTimerStopFromISR().

Here is the caller graph for this function:

IsLinked()

bool stk::util::DListEntry< Timer, TClosedLoop >::IsLinked ( ) const

inlineinherited

Check whether this entry is currently a member of any list.

Returns

true if linked (m_head != NULL); false otherwise.

Definition at line 127 of file stk_linked_list.h.

{ return (GetHead() != nullptr); }

Link()

void stk::util::DListEntry< Timer, TClosedLoop >::Link ( DLHeadType * head, DLEntryType * next, DLEntryType * prev )

inlineprivateinherited

Wire this entry into a list between prev and next.

Parameters

[in]	head	The owning DListHead. Stored as a back-pointer for IsLinked() and ownership checks.
[in]	next	The entry that will follow this one, or NULL if this becomes the last entry.
[in]	prev	The entry that will precede this one, or NULL if this becomes the first entry.

Note

Called exclusively by DListHead::Link(). Assumes the entry is not currently linked. Updates the neighbours' forward/back pointers to splice this entry in.

Definition at line 162 of file stk_linked_list.h.

    {
        m_head = head;
        m_next = next;
        m_prev = prev;
 
        if (m_prev != nullptr)
        {
            m_prev->m_next = this;
        }
 
        if (m_next != nullptr)
        {
            m_next->m_prev = this;
        }
    }

OnExpired()

virtual void stk::time::TimerHost::Timer::OnExpired ( TimerHost * host )

pure virtual

Callback invoked by the handler task when this timer expires.

Parameters

[in]

host

Pointer to the TimerHost that fired this timer.

Note

Executes in the context of a TimerHost handler task. Implementations must be safe to call from that task's context and should complete quickly, long-running work should be delegated (e.g. via an event or queue) to avoid blocking other expired timers.

Implemented in CTimerWrapper, FrtosPendDrainer, FrtosTimer, and StkTimer.

References TimerHost.

Referenced by stk::time::TimerHost::ProcessTimers().

Here is the call graph for this function:

Here is the caller graph for this function:

operator const Timer *()

stk::util::DListEntry< Timer, TClosedLoop >::operator const Timer * ( ) const

inlineinherited

Implicit conversion to a const pointer to the host object (T).

Note

Safe because T must derive from DListEntry<T, TClosedLoop>. Eliminates the need for explicit static_cast at call sites.

MISRA deviation: [STK-DEV-004] Rule 5-2-x.

Definition at line 141 of file stk_linked_list.h.

{ return static_cast<const T *>(this); }

operator Timer *()

stk::util::DListEntry< Timer, TClosedLoop >::operator Timer* ( )

inlineinherited

Implicit conversion to a mutable pointer to the host object (T).

Note

Safe because T must derive from DListEntry<T, TClosedLoop>. Eliminates the need for explicit static_cast at call sites.

MISRA deviation: [STK-DEV-004] Rule 5-2-x.

Definition at line 134 of file stk_linked_list.h.

{ return static_cast<T *>(this); }

STK_NONCOPYABLE_CLASS()

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

private

References Timer().

Here is the call graph for this function:

Unlink()

void stk::util::DListEntry< Timer, TClosedLoop >::Unlink ( )

inlineprivateinherited

Remove this entry from its current list.

Note

Called exclusively by DListHead::Unlink(). Patches the neighbours' pointers to bridge over this entry, then clears m_head, m_next, and m_prev to NULL so the entry is in a clean unlinked state.

Does not update DListHead::m_count or m_first / m_last — those are the responsibility of the calling DListHead::Unlink().

Definition at line 186 of file stk_linked_list.h.

    {
        if (m_prev != nullptr)
        {
            m_prev->m_next = m_next;
        }
 
        if (m_next != nullptr)
        {
            m_next->m_prev = m_prev;
        }
 
        m_head = nullptr;
        m_next = nullptr;
        m_prev = nullptr;
    }

Friends And Related Symbol Documentation

TimerHost

friend class TimerHost

friend

Definition at line 139 of file stk_time_timer.h.

References TimerHost.

Referenced by CTimerWrapper::OnExpired(), OnExpired(), and TimerHost.

util::DListCast

friend class util::DListCast

friend

Definition at line 140 of file stk_time_timer.h.

Member Data Documentation

m_active

volatile bool stk::time::TimerHost::Timer::m_active

private

true if active

Definition at line 207 of file stk_time_timer.h.

Referenced by GetRemainingTicks(), IsActive(), stk::time::TimerHost::ProcessCommands(), stk::time::TimerHost::Reset(), stk::time::TimerHost::SetPeriod(), stk::time::TimerHost::Start(), stk::time::TimerHost::Stop(), Timer(), and stk::time::TimerHost::UpdateTime().

m_deadline

Ticks stk::time::TimerHost::Timer::m_deadline

private

absolute expiration time (ticks)

Definition at line 204 of file stk_time_timer.h.

Referenced by GetDeadline(), GetRemainingTicks(), stk::time::TimerHost::ProcessCommands(), Timer(), and stk::time::TimerHost::UpdateTime().

m_head

DLHeadType* stk::util::DListEntry< Timer, TClosedLoop >::m_head

privateinherited

Owning list head, or NULL when the entry is not linked.

Definition at line 203 of file stk_linked_list.h.

m_next

DLEntryType* stk::util::DListEntry< Timer, TClosedLoop >::m_next

privateinherited

Next entry in the list, or NULL (open list boundary) / first entry (closed loop).

Definition at line 204 of file stk_linked_list.h.

m_pending

volatile bool stk::time::TimerHost::Timer::m_pending

private

true if pending to be handled

Definition at line 208 of file stk_time_timer.h.

Referenced by stk::time::TimerHost::ProcessCommands(), stk::time::TimerHost::ProcessTimers(), Timer(), and stk::time::TimerHost::UpdateTime().

m_period

uint32_t stk::time::TimerHost::Timer::m_period

private

reload period in ticks (0 = one-shot)

Definition at line 206 of file stk_time_timer.h.

Referenced by GetPeriod(), stk::time::TimerHost::ProcessCommands(), stk::time::TimerHost::Reset(), stk::time::TimerHost::SetPeriod(), Timer(), and stk::time::TimerHost::UpdateTime().

m_prev

DLEntryType* stk::util::DListEntry< Timer, TClosedLoop >::m_prev

privateinherited

Previous entry in the list, or NULL (open list boundary) / last entry (closed loop).

Definition at line 205 of file stk_linked_list.h.

m_rearming

volatile bool stk::time::TimerHost::Timer::m_rearming

private

true while a CMD_RESTART / CMD_START_OR_RESET is already in the command queue

Definition at line 209 of file stk_time_timer.h.

Referenced by stk::time::TimerHost::ProcessCommands(), stk::time::TimerHost::PushCommand(), and Timer().

m_timestamp

Ticks stk::time::TimerHost::Timer::m_timestamp

private

absolute time at which timer expired (ticks), updated by TimerHost

Definition at line 205 of file stk_time_timer.h.

Referenced by GetTimestamp(), Timer(), and stk::time::TimerHost::UpdateTime().

---

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

• stk_time_timer.h