STK C Timer API

Pure C interface for stk::time::TimerHost and stk::time::TimerHost::Timer. More...

Collaboration diagram for STK C Timer API:

Topics
	STK C PeriodicTrigger API
	Pure C interface for stk::time::PeriodicTrigger.

Macros
#define	STK_C_TIMER_MAX   (32U)
	Maximum number of concurrent stk_timer_t instances per core (default: 32). The total pool size is STK_C_TIMER_MAX × STK_C_CPU_COUNT slots, shared across all cores. When the pool is exhausted stk_timer_create() asserts in debug builds and returns NULL in release builds.
#define	STK_C_TIMER_HANDLER_STACK_SIZE   (256U)
	Stack size of the timer handler, increase if your timers consume more (default: 256).

Typedefs
typedef struct stk_timerhost_t	stk_timerhost_t
	Opaque handle to a TimerHost instance (one per CPU core).
typedef struct stk_timer_t	stk_timer_t
	Opaque handle to a concrete timer managed by stk_timerhost_t.
typedef void(*	stk_timer_callback_t) (stk_timerhost_t *host, stk_timer_t *timer, void *user_data)
	Timer expiration callback invoked from within the TimerHost handler task.

Functions
stk_timerhost_t *	stk_timerhost_get (uint8_t core_nr)
	Obtain the pre-allocated TimerHost for the given CPU core.
void	stk_timerhost_init (stk_timerhost_t *host, stk_kernel_t *kernel, bool privileged)
	Initialize the TimerHost and register its internal tasks with the kernel.
bool	stk_timerhost_shutdown (stk_timerhost_t *host)
	Gracefully shut down the TimerHost.
bool	stk_timerhost_is_empty (const stk_timerhost_t *host)
	Return true when no timers are currently active on this host.
size_t	stk_timerhost_get_size (const stk_timerhost_t *host)
	Return the number of currently active timers on this host.
int64_t	stk_timerhost_get_time_now (const stk_timerhost_t *host)
	Return the last tick count snapshot maintained by the host's tick task.
stk_timer_t *	stk_timer_create (stk_timer_callback_t callback, void *user_data)
	Allocate a timer from the static pool.
void	stk_timer_destroy (stk_timer_t *tmr)
	Return a timer handle back to the static pool.
bool	stk_timer_start (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
	Start a timer.
bool	stk_timer_stop (stk_timerhost_t *host, stk_timer_t *tmr)
	Stop a running timer.
bool	stk_timer_reset (stk_timerhost_t *host, stk_timer_t *tmr)
	Reset a periodic timer's deadline (re-arm from now).
bool	stk_timer_restart (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
	Atomically stop and re-start a timer.
bool	stk_timer_start_or_reset (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period_ticks)
	Start the timer if inactive, or reset its deadline if already active and periodic.
bool	stk_timer_set_period (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t period_ticks)
	Change the period of a running periodic timer without affecting the current deadline.
bool	stk_timer_is_active (const stk_timer_t *tmr)
	Check whether a timer is currently active (started and not yet expired/stopped).
uint32_t	stk_timer_get_period (const stk_timer_t *tmr)
	Get the timer's reload period.
int64_t	stk_timer_get_deadline (const stk_timer_t *tmr)
	Get the absolute expiration tick count of the timer's next deadline.
int64_t	stk_timer_get_timestamp (const stk_timer_t *tmr)
	Get the tick count at which the timer last expired.
uint32_t	stk_timer_get_remaining_ticks (const stk_timer_t *tmr)
	Get remaining ticks until next expiration.

Detailed Description

Pure C interface for stk::time::TimerHost and stk::time::TimerHost::Timer.

Macro Definition Documentation

STK_C_TIMER_HANDLER_STACK_SIZE

#define STK_C_TIMER_HANDLER_STACK_SIZE   (256U)

Stack size of the timer handler, increase if your timers consume more (default: 256).

Definition at line 55 of file stk_c_time.h.

STK_C_TIMER_MAX

#define STK_C_TIMER_MAX   (32U)

Maximum number of concurrent stk_timer_t instances per core (default: 32). The total pool size is STK_C_TIMER_MAX × STK_C_CPU_COUNT slots, shared across all cores. When the pool is exhausted stk_timer_create() asserts in debug builds and returns NULL in release builds.

Note

Increase if your application needs more simultaneous timers.

Definition at line 48 of file stk_c_time.h.

Typedef Documentation

stk_timer_callback_t

typedef void(* stk_timer_callback_t) (stk_timerhost_t *host, stk_timer_t *timer, void *user_data)

Timer expiration callback invoked from within the TimerHost handler task.

Parameters

[in]	host	TimerHost that fired the timer.
[in]	timer	The timer that expired.
[in]	user_data	Opaque pointer supplied at timer creation time.

Warning

Must not call blocking kernel services (e.g. stk_mutex_lock with a non-zero timeout) unless the handler task stack is large enough.

Definition at line 77 of file stk_c_time.h.

stk_timer_t

typedef struct stk_timer_t stk_timer_t

Opaque handle to a concrete timer managed by stk_timerhost_t.

Definition at line 68 of file stk_c_time.h.

stk_timerhost_t

typedef struct stk_timerhost_t stk_timerhost_t

Opaque handle to a TimerHost instance (one per CPU core).

Definition at line 64 of file stk_c_time.h.

Function Documentation

stk_timer_create()

stk_timer_t * stk_timer_create	(	stk_timer_callback_t	callback,
		void *	user_data )

Allocate a timer from the static pool.

Parameters

[in]	callback	Function to call when the timer expires (must not be NULL).
[in]	user_data	Opaque pointer forwarded to callback on expiration.

Returns

Timer handle, or NULL if the pool is exhausted (STK_C_TIMER_MAX × STK_C_CPU_COUNT slots total).

Note

The returned handle is valid until stk_timer_destroy() is called. It must not be active (i.e. not currently started) when destroyed.

The pool is shared across all CPU cores. Total capacity is STK_C_TIMER_MAX * STK_C_CPU_COUNT.

Definition at line 196 of file stk_c_time.cpp.

{
    STK_ASSERT(callback != nullptr);
 
    const sync::ScopedCriticalSection __cs;
 
    stk_timer_t *result = nullptr;
 
    for (uint32_t i = 0U; i < STK_C_TIMERS_TOTAL; ++i)
    {
        if (!s_Timers[i].busy)
        {
            s_Timers[i].busy = true;
            s_Timers[i].timer.handle.Initialize(callback, user_data);
            result = &s_Timers[i].timer;
            break;
        }
    }
 
    // pool exhausted, you must increase STK_C_TIMER_MAX
    STK_ASSERT(result != nullptr);
 
    return result;
}

References s_Timers, STK_ASSERT, and STK_C_TIMERS_TOTAL.

stk_timer_destroy()

void stk_timer_destroy

(

stk_timer_t *

tmr

)

Return a timer handle back to the static pool.

Parameters

[in]

tmr

Timer handle.

Warning

The timer must have been stopped (or never started) before calling this. Destroying an active timer is a programming error and triggers an assertion.

Definition at line 221 of file stk_c_time.cpp.

{
    STK_ASSERT(tmr != nullptr);
 
    // destroying an active timer is a programming error
    STK_ASSERT(!tmr->handle.IsActive());
 
    const sync::ScopedCriticalSection __cs;
 
    bool found = false;
 
    for (uint32_t i = 0U; ((i < STK_C_TIMERS_TOTAL) && !found); ++i)
    {
        if (s_Timers[i].busy && (&s_Timers[i].timer == tmr))
        {
            tmr->handle.Reset();
            s_Timers[i].busy = false;
            found = true;
        }
    }
 
    // timer not found in the pool: indicates a double-free or corruption
    STK_ASSERT(found);
}

References stk_timer_t::handle, stk::time::TimerHost::Timer::IsActive(), CTimerWrapper::Reset(), s_Timers, STK_ASSERT, and STK_C_TIMERS_TOTAL.

Here is the call graph for this function:

stk_timer_get_deadline()

int64_t stk_timer_get_deadline

(

const stk_timer_t *

tmr

)

Get the absolute expiration tick count of the timer's next deadline.

Parameters

[in]

tmr

Timer handle.

Returns

Absolute deadline (ticks). Meaningful only when the timer is active.

Definition at line 331 of file stk_c_time.cpp.

{
    STK_ASSERT(tmr != nullptr);
 
    return static_cast<int64_t>(tmr->handle.GetDeadline());
}

References stk::time::TimerHost::Timer::GetDeadline(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_get_period()

uint32_t stk_timer_get_period

(

const stk_timer_t *

tmr

)

Get the timer's reload period.

Parameters

[in]

tmr

Timer handle.

Returns

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

Definition at line 324 of file stk_c_time.cpp.

{
    STK_ASSERT(tmr != nullptr);
 
    return tmr->handle.GetPeriod();
}

References stk::time::TimerHost::Timer::GetPeriod(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_get_remaining_ticks()

uint32_t stk_timer_get_remaining_ticks

(

const stk_timer_t *

tmr

)

Get remaining ticks until next expiration.

Parameters

[in]

tmr

Timer handle.

Returns

Remaining ticks, or 0 if already expired or not active.

Note

Computed from the last value written by the host's tick task - may be up to one tick-task wake cycle stale.

Definition at line 345 of file stk_c_time.cpp.

{
    STK_ASSERT(tmr != nullptr);
 
    return tmr->handle.GetRemainingTicks();
}

References stk::time::TimerHost::Timer::GetRemainingTicks(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_get_timestamp()

int64_t stk_timer_get_timestamp

(

const stk_timer_t *

tmr

)

Get the tick count at which the timer last expired.

Parameters

[in]

tmr

Timer handle.

Returns

Expiration timestamp (ticks). Zero if the timer has never fired.

Definition at line 338 of file stk_c_time.cpp.

{
    STK_ASSERT(tmr != nullptr);
 
    return static_cast<int64_t>(tmr->handle.GetTimestamp());
}

References stk::time::TimerHost::Timer::GetTimestamp(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_is_active()

bool stk_timer_is_active

(

const stk_timer_t *

tmr

)

Check whether a timer is currently active (started and not yet expired/stopped).

Parameters

[in]

tmr

Timer handle.

Returns

true if the timer is active.

Note

Advisory - may change immediately after the call.

Definition at line 317 of file stk_c_time.cpp.

{
    STK_ASSERT(tmr != nullptr);
 
    return tmr->handle.IsActive();
}

References stk_timer_t::handle, stk::time::TimerHost::Timer::IsActive(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_reset()

bool stk_timer_reset	(	stk_timerhost_t *	host,
		stk_timer_t *	tmr )

Reset a periodic timer's deadline (re-arm from now).

Parameters

[in]	host	TimerHost managing the timer.
[in]	tmr	Timer handle. Must be active and periodic (period != 0).

Returns

true on success, false if preconditions are not met or the command queue is full.

Definition at line 275 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(tmr != nullptr);
 
    return host->handle.Reset(tmr->handle);
}

References stk_timer_t::handle, stk_timerhost_t::handle, stk::time::TimerHost::Reset(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_restart()

bool stk_timer_restart	(	stk_timerhost_t *	host,
		stk_timer_t *	tmr,
		uint32_t	delay,
		uint32_t	period )

Atomically stop and re-start a timer.

Unlike calling stk_timer_stop() + stk_timer_start(), this operation is atomic with respect to the tick task: the timer cannot fire between the implicit stop and re-start. Consumes only one command queue slot.

Parameters

[in]	host	TimerHost managing the timer.
[in]	tmr	Timer handle (active or inactive).
[in]	delay	Initial delay in ticks before the first expiration.
[in]	period	Reload period in ticks (0 = one-shot).

Returns

true on success, false if the command queue is full.

Definition at line 283 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(tmr != nullptr);
 
    // refresh host association before timer can fire
    tmr->handle.SetHostHandle(host);
 
    return host->handle.Restart(tmr->handle, delay, period);
}

References stk_timer_t::handle, stk_timerhost_t::handle, stk::time::TimerHost::Restart(), CTimerWrapper::SetHostHandle(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_set_period()

bool stk_timer_set_period	(	stk_timerhost_t *	host,
		stk_timer_t *	tmr,
		uint32_t	period_ticks )

Change the period of a running periodic timer without affecting the current deadline.

The new period takes effect on the next reload after the current deadline fires. To apply immediately, follow with stk_timer_reset().

Parameters

[in]	host	TimerHost managing the timer.
[in]	tmr	Timer handle. Must be active and periodic.
[in]	period_ticks	New reload period in ticks. Must be non-zero.

Returns

true on success, false if preconditions are not met or the command queue is full.

Definition at line 305 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(tmr != nullptr);
 
    return host->handle.SetPeriod(tmr->handle, period_ticks);
}

References stk_timer_t::handle, stk_timerhost_t::handle, stk::time::TimerHost::SetPeriod(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_start()

bool stk_timer_start	(	stk_timerhost_t *	host,
		stk_timer_t *	tmr,
		uint32_t	delay,
		uint32_t	period )

Start a timer.

Parameters

[in]	host	TimerHost that will manage this timer.
[in]	tmr	Timer handle. Must not already be active.
[in]	delay	Initial delay in ticks before the first expiration.
[in]	period	Reload period in ticks. Pass 0 for a one-shot timer.

Returns

true on success, false if the timer is already active or the command queue is full.

Definition at line 253 of file stk_c_time.cpp.

{
    STK_ASSERT(host  != nullptr);
    STK_ASSERT(tmr != nullptr);
 
    // refresh host association before timer can fire
    tmr->handle.SetHostHandle(host);
 
    return host->handle.Start(tmr->handle, delay, period);
}

References stk_timer_t::handle, stk_timerhost_t::handle, CTimerWrapper::SetHostHandle(), stk::time::TimerHost::Start(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_start_or_reset()

bool stk_timer_start_or_reset	(	stk_timerhost_t *	host,
		stk_timer_t *	tmr,
		uint32_t	delay,
		uint32_t	period_ticks )

Start the timer if inactive, or reset its deadline if already active and periodic.

Collapses the common pattern:

if (stk_timer_is_active(t)) stk_timer_reset(host, t);
else                        stk_timer_start(host, t, delay, period);

into a single atomic operation, eliminating the TOCTOU race. If the timer is active but one-shot, no action is taken.

Parameters

[in]	host	TimerHost managing the timer.
[in]	tmr	Timer handle (active or inactive).
[in]	delay	Initial delay in ticks (used only when starting).
[in]	period_ticks	Reload period in ticks (used only when starting, 0 = one-shot).

Returns

true on success, false if the command queue is full.

Definition at line 294 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(tmr != nullptr);
 
    // refresh host association (harmless if timer is already active on host)
    tmr->handle.SetHostHandle(host);
 
    return host->handle.StartOrReset(tmr->handle, delay, period_ticks);
}

References stk_timer_t::handle, stk_timerhost_t::handle, CTimerWrapper::SetHostHandle(), stk::time::TimerHost::StartOrReset(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_stop()

bool stk_timer_stop	(	stk_timerhost_t *	host,
		stk_timer_t *	tmr )

Stop a running timer.

Parameters

[in]	host	TimerHost managing the timer.
[in]	tmr	Timer handle. Must be currently active.

Returns

true on success, false if the timer is not active or the command queue is full.

Definition at line 267 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(tmr != nullptr);
 
    return host->handle.Stop(tmr->handle);
}

References stk_timer_t::handle, stk_timerhost_t::handle, STK_ASSERT, and stk::time::TimerHost::Stop().

Here is the call graph for this function:

stk_timerhost_get()

stk_timerhost_t * stk_timerhost_get

(

uint8_t

core_nr

)

Obtain the pre-allocated TimerHost for the given CPU core.

Parameters

[in]

core_nr

CPU core index (0 … STK_C_CPU_COUNT-1).

Returns

TimerHost handle, or NULL if core_nr is out of range.

Note

The host instance exists in static storage; do not free it.

Definition at line 141 of file stk_c_time.cpp.

{
    stk_timerhost_t *result = nullptr;
 
    if (core_nr < STK_C_CPU_COUNT)
    {
        result = &s_TimerHosts[core_nr];
    }
 
    return result;
}

References s_TimerHosts, and STK_C_CPU_COUNT.

stk_timerhost_get_size()

size_t stk_timerhost_get_size

(

const stk_timerhost_t *

host

)

Return the number of currently active timers on this host.

Parameters

[in]

host

TimerHost handle.

Returns

Advisory active timer count (may change immediately after the call).

Definition at line 178 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return host->handle.GetSize();
}

References stk::time::TimerHost::GetSize(), stk_timerhost_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_get_time_now()

int64_t stk_timerhost_get_time_now

(

const stk_timerhost_t *

host

)

Return the last tick count snapshot maintained by the host's tick task.

Parameters

[in]

host

TimerHost handle.

Returns

Tick count (may be one tick-task wake cycle stale).

Definition at line 185 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return static_cast<int64_t>(host->handle.GetTimeNow());
}

References stk::time::TimerHost::GetTimeNow(), stk_timerhost_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_init()

void stk_timerhost_init	(	stk_timerhost_t *	host,
		stk_kernel_t *	kernel,
		bool	privileged )

Initialize the TimerHost and register its internal tasks with the kernel.

Parameters

[in]	host	TimerHost handle obtained via stk_timerhost_get().
[in]	kernel	Kernel instance the timer tasks will be added to.
[in]	privileged	If true the internal handler tasks run in privileged mode, otherwise they run in user mode.

Note

Must be called before stk_kernel_start() and before any stk_timer_* operations on this host.

Definition at line 153 of file stk_c_time.cpp.

{
    STK_ASSERT(host   != nullptr);
    STK_ASSERT(kernel != nullptr);
    
    interop_c_helper::InitializeTimerHost(kernel, &host->handle, 
        (privileged ? ACCESS_PRIVILEGED : ACCESS_USER));
}

References stk::ACCESS_PRIVILEGED, stk::ACCESS_USER, stk_timerhost_t::handle, stk::interop_c_helper::InitializeTimerHost(), and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_is_empty()

bool stk_timerhost_is_empty

(

const stk_timerhost_t *

host

)

Return true when no timers are currently active on this host.

Parameters

[in]

host

TimerHost handle.

Returns

Advisory empty flag (may change immediately after the call).

Definition at line 171 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return host->handle.IsEmpty();
}

References stk_timerhost_t::handle, stk::time::TimerHost::IsEmpty(), and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_shutdown()

bool stk_timerhost_shutdown

(

stk_timerhost_t *

host

)

Gracefully shut down the TimerHost.

Parameters

[in]

host

TimerHost handle.

Returns

true on success, false if the internal command queue is full.

Note

All active timers are stopped. After shutdown the host must not be used.

Definition at line 164 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return host->handle.Shutdown();
}

References stk_timerhost_t::handle, stk::time::TimerHost::Shutdown(), and STK_ASSERT.

Here is the call graph for this function: