STK C PeriodicTrigger API

Pure C interface for stk::time::PeriodicTrigger. More...

Collaboration diagram for STK C PeriodicTrigger API:

Classes
struct	stk_periodic_trigger_mem_t
	Opaque memory container for a stk_periodic_trigger_t instance. More...

Macros
#define	STK_PERIODIC_TRIGGER_IMPL_SIZE   (16U)
	A memory size (multiples of stk_word_t) required for PeriodicTrigger instance.

Typedefs
typedef struct stk_periodic_trigger_mem_t	stk_periodic_trigger_mem_t
	Opaque memory container for a stk_periodic_trigger_t instance.
typedef struct stk_periodic_trigger_t	stk_periodic_trigger_t
	Opaque handle to a stk::time::PeriodicTrigger instance.

Functions
stk_periodic_trigger_t *	stk_periodic_trigger_create (stk_periodic_trigger_mem_t *const membuf, uint32_t membuf_size, uint32_t period_ticks, bool started)
	Construct PeriodicTrigger instance in the supplied memory buffer.
void	stk_periodic_trigger_destroy (stk_periodic_trigger_t *const trig)
	Destroy instance (calls the C++ destructor in-place).
bool	stk_periodic_trigger_poll (stk_periodic_trigger_t *trig)
	Check whether the scheduled trigger time has been reached.
void	stk_periodic_trigger_set_period (stk_periodic_trigger_t *trig, uint32_t period_ticks)
	Change the trigger period while preserving phase.
void	stk_periodic_trigger_restart (stk_periodic_trigger_t *trig)
	Reset and start the trigger from the current tick count.
uint32_t	stk_periodic_trigger_get_period (const stk_periodic_trigger_t *trig)
	Get currently configured trigger period.

Detailed Description

Pure C interface for stk::time::PeriodicTrigger.

Typical usage:

static stk_periodic_trigger_mem_t mem;
stk_periodic_trigger_t *trig = stk_periodic_trigger_create(&mem, sizeof(mem), 500, true);
 
// Inside a task loop:
if (stk_periodic_trigger_poll(trig))
{
    // executed once per 500-tick period
}

Macro Definition Documentation

STK_PERIODIC_TRIGGER_IMPL_SIZE

#define STK_PERIODIC_TRIGGER_IMPL_SIZE   (16U)

A memory size (multiples of stk_word_t) required for PeriodicTrigger instance.

Definition at line 293 of file stk_c_time.h.

Typedef Documentation

stk_periodic_trigger_mem_t

typedef struct stk_periodic_trigger_mem_t stk_periodic_trigger_mem_t

Opaque memory container for a stk_periodic_trigger_t instance.

Note

Declare as static or on the stack (not on the heap).

stk_periodic_trigger_t

typedef struct stk_periodic_trigger_t stk_periodic_trigger_t

Opaque handle to a stk::time::PeriodicTrigger instance.

Definition at line 304 of file stk_c_time.h.

Function Documentation

stk_periodic_trigger_create()

stk_periodic_trigger_t * stk_periodic_trigger_create	(	stk_periodic_trigger_mem_t *const	membuf,
		uint32_t	membuf_size,
		uint32_t	period_ticks,
		bool	started )

Construct PeriodicTrigger instance in the supplied memory buffer.

Parameters

[in]	membuf	Pointer to the caller-supplied memory container.
[in]	membuf_size	Size of the container in bytes (must be >= sizeof(stk_periodic_trigger_mem_t)).
[in]	period_ticks	Trigger period in ticks. Must be > 0.
[in]	started	true to create the instance in a started state (first firing occurs no earlier than period ticks after construction); false to create it in a stopped state (call stk_periodic_trigger_restart() before polling).

Returns

Trigger handle on success, or NULL if membuf is NULL or memory_size is too small.

Definition at line 364 of file stk_c_time.cpp.

{
    STK_ASSERT(membuf != nullptr);
    STK_ASSERT(membuf_size >= sizeof(stk_periodic_trigger_t));
    STK_STATIC_ASSERT_N((sizeof(stk_periodic_trigger_t) <= sizeof(stk_periodic_trigger_mem_t)),
        "stk_periodic_trigger_mem_t is too small to hold stk_periodic_trigger_t");
 
    stk_periodic_trigger_t *result = nullptr;
    if (membuf_size >= sizeof(stk_periodic_trigger_t))
    {      
        result = new (membuf->data) stk_periodic_trigger_t(period_ticks, started);
    }
 
    return result;
}

References stk_periodic_trigger_mem_t::data, STK_ASSERT, and STK_STATIC_ASSERT_N.

stk_periodic_trigger_destroy()

void stk_periodic_trigger_destroy

(

stk_periodic_trigger_t *const

trig

)

Destroy instance (calls the C++ destructor in-place).

Parameters

[in]

trig

Trigger handle. May be NULL (no-op).

Definition at line 383 of file stk_c_time.cpp.

{
    if (trig != nullptr)
    {
        trig->~stk_periodic_trigger_t();
    }
}

stk_periodic_trigger_get_period()

uint32_t stk_periodic_trigger_get_period

(

const stk_periodic_trigger_t *

trig

)

Get currently configured trigger period.

Parameters

[in]

trig

Trigger handle.

Returns

Period in ticks.

Definition at line 412 of file stk_c_time.cpp.

{
    STK_ASSERT(trig != nullptr);
 
    return static_cast<uint32_t>(trig->handle.GetPeriod());
}

References stk::time::PeriodicTrigger::GetPeriod(), stk_periodic_trigger_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_periodic_trigger_poll()

bool stk_periodic_trigger_poll

(

stk_periodic_trigger_t *

trig

)

Check whether the scheduled trigger time has been reached.

Parameters

[in]

trig

Trigger handle (must be started).

Returns

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

Note

Implements absolute-time scheduling. When firing occurs, the internal next-trigger time is advanced by exactly one period (not reset to the current time), preserving long-term frequency stability.

At most one true is returned per call. If multiple full periods have elapsed since the previous call, subsequent calls will continue advancing one period at a time until the schedule catches up.

Definition at line 391 of file stk_c_time.cpp.

{
    STK_ASSERT(trig != nullptr);
 
    return trig->handle.Poll();
}

References stk_periodic_trigger_t::handle, stk::time::PeriodicTrigger::Poll(), and STK_ASSERT.

Here is the call graph for this function:

stk_periodic_trigger_restart()

void stk_periodic_trigger_restart

(

stk_periodic_trigger_t *

trig

)

Reset and start the trigger from the current tick count.

Parameters

[in]

trig

Trigger handle.

Note

Sets the internal next-trigger time to (current ticks + period). The next firing occurs no earlier than period ticks after this call. Does not change the configured period.

Definition at line 405 of file stk_c_time.cpp.

{
    STK_ASSERT(trig != nullptr);
 
    trig->handle.Restart();
}

References stk_periodic_trigger_t::handle, stk::time::PeriodicTrigger::Restart(), and STK_ASSERT.

Here is the call graph for this function:

stk_periodic_trigger_set_period()

void stk_periodic_trigger_set_period	(	stk_periodic_trigger_t *	trig,
		uint32_t	period_ticks )

Change the trigger period while preserving phase.

Parameters

[in]	trig	Trigger handle.
[in]	period_ticks	New trigger period in ticks. Must be > 0.

Note

Adjusts the internally stored next-trigger time so that the relative progress toward the next firing is preserved. Takes effect immediately.

Definition at line 398 of file stk_c_time.cpp.

{
    STK_ASSERT(trig != nullptr);
 
    trig->handle.SetPeriod(period_ticks);
}

References stk_periodic_trigger_t::handle, stk::time::PeriodicTrigger::SetPeriod(), and STK_ASSERT.

Here is the call graph for this function: