SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk_timer_t Struct Referencefinal
Inheritance diagram for stk_timer_t:
Collaboration diagram for stk_timer_t:

Public Types

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

Public Member Functions

 stk_timer_t (stk_timer_callback_t callback, void *user_data)
void SetHostHandle (stk_timerhost_t *host_handle)
void OnExpired (TimerHost *host) override
 Callback invoked 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 GetDelay () const
 Get the initial delay stored by the last start/restart/change command.
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

stk_timerhost_t * m_host_handle
 C-level host, forwarded to the callback.
stk_timer_callback_t m_callback
void * m_user_data
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)
uint32_t m_delay
 initial delay in ticks of the last start/restart/change (reused by CMD_ACTIVATE)
volatile bool m_active
 true if active
volatile bool m_pending
 true if pending to be handled (task mode: m_ready_node is linked)
volatile bool m_rearming
 true while a CMD_RESTART / CMD_START_OR_RESET is already in the command queue
ReadyNode m_ready_node
 hook in the ready list of the host (task mode), see ReadyNode
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).

Detailed Description

Examples
low_power_c/example.c, and timer_c/example.c.

Definition at line 29 of file stk_c_time.cpp.

Member Typedef Documentation

◆ DLEntryType

typedef DListEntry<Timer, TClosedLoop> stk::detail::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::detail::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
inherited

A tag for type-safe casts done by CastListEntryToParent.

See also
CastListEntryToParent.
Enumerator
DLEntryTag 

Definition at line 103 of file stk_time_timer.h.

◆ 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.

70{ DLEntryTag = 1 };
Intrusive doubly-linked list node. Embed this as a base class in any object (T) that needs to partici...

Constructor & Destructor Documentation

◆ stk_timer_t()

stk_timer_t::stk_timer_t ( stk_timer_callback_t callback,
void * user_data )
inline

Definition at line 31 of file stk_c_time.cpp.

32 : m_host_handle(nullptr), m_callback(callback), m_user_data(user_data)
33 {
34 STK_ASSERT(callback != nullptr);
35 }
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
void * m_user_data
stk_timerhost_t * m_host_handle
C-level host, forwarded to the callback.
stk_timer_callback_t m_callback

References m_callback, m_host_handle, m_user_data, and STK_ASSERT.

Member Function Documentation

◆ GetDeadline()

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

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 129 of file stk_time_timer.h.

129{ return m_deadline; }
Ticks m_deadline
absolute expiration time (ticks)

References m_deadline.

Referenced by stk_timer_get_deadline().

Here is the caller graph for this function:

◆ GetDelay()

uint32_t stk::time::Timer::GetDelay ( ) const
inlineinherited

Get the initial delay stored by the last start/restart/change command.

Returns
Delay in ticks, 0 if none was stored yet.
Note
Used by TimerHost::ActivateSync() to (re)start the timer with its stored parameters.

Definition at line 146 of file stk_time_timer.h.

146{ return m_delay; }
uint32_t m_delay
initial delay in ticks of the last start/restart/change (reused by CMD_ACTIVATE)

References m_delay.

◆ GetHead()

DLHeadType * stk::detail::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.

85{ return m_head; }

◆ GetNext()

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

Get the next entry in the list.

Returns
Next entry. In an open list NULL for the last entry; in a closed loop the last entry wraps to the first one, so the result is never NULL for a linked entry.

Definition at line 96 of file stk_linked_list.h.

96{ return m_next; }

◆ GetPeriod()

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

Get the reload period of the timer.

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

Definition at line 140 of file stk_time_timer.h.

140{ return m_period; }
uint32_t m_period
reload period in ticks (0 = one-shot)

References m_period.

Referenced by stk_timer_get_period().

Here is the caller graph for this function:

◆ GetPrev()

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

Get the previous entry in the list.

Returns
Previous entry. In an open list NULL for the first entry; in a closed loop the first entry wraps to the last one, so the result is never NULL for a linked entry.

Definition at line 106 of file stk_linked_list.h.

106{ return m_prev; }

◆ GetRemainingTicks()

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

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 1015 of file stk_time_timer.h.

1016{
1017 uint32_t remaining_ticks = 0U;
1018
1019 if (m_active)
1020 {
1021 // if deadline has passed but not yet been processed by the tick task,
1022 // remaining would be negative, result fits in uint32_t because delay and
1023 // period are uint32_t, so remaining time is bounded by uint32_t max
1024 const Ticks remaining = m_deadline - GetTicks();
1025
1026 if (remaining > 0)
1027 {
1028 remaining_ticks = static_cast<uint32_t>(remaining);
1029 }
1030 }
1031
1032 return remaining_ticks;
1033}
int64_t Ticks
Ticks value.
Definition stk_common.h:221
static Ticks GetTicks()
Get number of ticks elapsed since kernel start.
Definition stk_helper.h:448
volatile bool m_active
true if active

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

Referenced by stk::time::TimerHost::Execute(), and 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::Timer::GetTimestamp ( ) const
inlineinherited

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 135 of file stk_time_timer.h.

135{ return m_timestamp; }
Ticks m_timestamp
absolute time at which timer expired (ticks), updated by TimerHost

References m_timestamp.

Referenced by stk_timer_get_timestamp().

Here is the caller graph for this function:

◆ IsActive()

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

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 123 of file stk_time_timer.h.

123{ return m_active; }

References m_active.

Referenced by cy_rtos_timer_is_running(), stk_timer_destroy(), and stk_timer_is_active().

Here is the caller graph for this function:

◆ IsLinked()

bool stk::detail::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 115 of file stk_linked_list.h.

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

◆ Link()

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

Wire this entry into a list between prev and next.

Parameters
[in]headThe owning DListHead. Stored as a back-pointer for IsLinked() and ownership checks.
[in]nextThe entry that will follow this one, or NULL if this becomes the last entry.
[in]prevThe 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 150 of file stk_linked_list.h.

151 {
152 m_head = head;
153 m_next = next;
154 m_prev = prev;
155
156 if (m_prev != nullptr)
157 {
158 m_prev->m_next = this;
159 }
160
161 if (m_next != nullptr)
162 {
163 m_next->m_prev = this;
164 }
165 }
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).

◆ OnExpired()

void stk_timer_t::OnExpired ( TimerHost * host)
inlineoverridevirtual

Callback invoked when this timer expires.

Parameters
[in]hostPointer to the TimerHost that fired this timer.
Note
Task mode: executes in the context of a TimerHost handler task. Polled mode: executes inline in the context which calls TimerHost::Process().
Implementations must be safe to call from that context and should complete quickly, long-running work should be delegated (e.g. via an event or queue) to avoid blocking other expired timers. In polled mode (e.g. an HRT job) the execution time counts against the deadline of the job which calls Process(), and the callback must not call Process() itself.

Implements stk::time::Timer.

Definition at line 42 of file stk_c_time.cpp.

43 {
44 STK_UNUSED(host);
45
46 if (m_callback != nullptr)
47 {
49 }
50 }
#define STK_UNUSED(X)
Explicitly marks a variable as unused to suppress compiler warnings.
Definition stk_defs.h:715

References m_callback, m_host_handle, m_user_data, STK_UNUSED, and stk::time::Timer::TimerHost.

Here is the call graph for this function:

◆ operator const Timer *()

stk::detail::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 129 of file stk_linked_list.h.

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

◆ operator Timer *()

stk::detail::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 122 of file stk_linked_list.h.

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

◆ SetHostHandle()

void stk_timer_t::SetHostHandle ( stk_timerhost_t * host_handle)
inline

Definition at line 40 of file stk_c_time.cpp.

40{ m_host_handle = host_handle; }

References m_host_handle.

Referenced by stk_timer_activate_sync(), stk_timer_change_sync(), stk_timer_restart(), stk_timer_restart_sync(), stk_timer_start(), stk_timer_start_or_reset(), and stk_timer_start_sync().

Here is the caller graph for this function:

◆ STK_NONCOPYABLE_CLASS()

stk::time::Timer::STK_NONCOPYABLE_CLASS ( Timer )
privateinherited

References Timer().

Here is the call graph for this function:

◆ Unlink()

void stk::detail::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 174 of file stk_linked_list.h.

175 {
176 if (m_prev != nullptr)
177 {
179 }
180
181 if (m_next != nullptr)
182 {
184 }
185
186 m_head = nullptr;
187 m_next = nullptr;
188 m_prev = nullptr;
189 }

Member Data Documentation

◆ m_active

◆ m_callback

stk_timer_callback_t stk_timer_t::m_callback
private

Definition at line 54 of file stk_c_time.cpp.

Referenced by OnExpired(), and stk_timer_t().

◆ m_deadline

Ticks stk::time::Timer::m_deadline
privateinherited

absolute expiration time (ticks)

Definition at line 178 of file stk_time_timer.h.

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

◆ m_delay

uint32_t stk::time::Timer::m_delay
privateinherited

initial delay in ticks of the last start/restart/change (reused by CMD_ACTIVATE)

Definition at line 181 of file stk_time_timer.h.

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

◆ m_head

DLHeadType* stk::detail::DListEntry< Timer, TClosedLoop >::m_head
privateinherited

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

Definition at line 191 of file stk_linked_list.h.

◆ m_host_handle

stk_timerhost_t* stk_timer_t::m_host_handle
private

C-level host, forwarded to the callback.

Definition at line 53 of file stk_c_time.cpp.

Referenced by OnExpired(), SetHostHandle(), and stk_timer_t().

◆ m_next

DLEntryType* stk::detail::DListEntry< Timer, TClosedLoop >::m_next
privateinherited

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

Definition at line 192 of file stk_linked_list.h.

◆ m_pending

volatile bool stk::time::Timer::m_pending
privateinherited

true if pending to be handled (task mode: m_ready_node is linked)

Definition at line 183 of file stk_time_timer.h.

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

◆ m_period

uint32_t stk::time::Timer::m_period
privateinherited

◆ m_prev

DLEntryType* stk::detail::DListEntry< Timer, TClosedLoop >::m_prev
privateinherited

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

Definition at line 193 of file stk_linked_list.h.

◆ m_ready_node

ReadyNode stk::time::Timer::m_ready_node
privateinherited

hook in the ready list of the host (task mode), see ReadyNode

Definition at line 185 of file stk_time_timer.h.

Referenced by stk::time::TimerHost::CancelPending(), stk::time::TimerHost::ScanTimers(), and Timer().

◆ m_rearming

volatile bool stk::time::Timer::m_rearming
privateinherited

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

Definition at line 184 of file stk_time_timer.h.

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

◆ m_timestamp

Ticks stk::time::Timer::m_timestamp
privateinherited

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

Definition at line 179 of file stk_time_timer.h.

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

◆ m_user_data

void* stk_timer_t::m_user_data
private

Definition at line 55 of file stk_c_time.cpp.

Referenced by OnExpired(), and stk_timer_t().


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