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   16
	A memory size (multiples of size_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 *memory, uint32_t memory_size, uint32_t period, bool started)
	Construct PeriodicTrigger instance in the supplied memory buffer.
void	stk_periodic_trigger_destroy (stk_periodic_trigger_t *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)
	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   16

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

Definition at line 287 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 298 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 *	memory,
		uint32_t	memory_size,
		uint32_t	period,
		bool	started )

Construct PeriodicTrigger instance in the supplied memory buffer.

Parameters

[in]	memory	Pointer to the caller-supplied memory container.
[in]	memory_size	Size of the container in bytes (must be >= sizeof(stk_periodic_trigger_mem_t)).
[in]	period	Trigger period in ticks. Must be > 0.
[in]	started	true to create instance in a started state, false otherwise.

Returns

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

Note

The trigger is created in a stopped state. Call stk_periodic_trigger_restart() before polling.

Definition at line 340 of file stk_c_time.cpp.

{
    STK_ASSERT(memory != nullptr);
    STK_ASSERT(memory_size >= sizeof(stk_periodic_trigger_t));
    if (memory == nullptr || memory_size < sizeof(stk_periodic_trigger_t))
        return nullptr;
 
    return new (memory->data) stk_periodic_trigger_t{ time::PeriodicTrigger(static_cast<Ticks>(period), started) };
}

References stk_periodic_trigger_mem_t::data, and STK_ASSERT.

stk_periodic_trigger_destroy()

void stk_periodic_trigger_destroy

(

stk_periodic_trigger_t *

trig

)

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

Parameters

[in]

trig

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

Definition at line 353 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 380 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 359 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 373 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 )

Change the trigger period while preserving phase.

Parameters

[in]	trig	Trigger handle.
[in]	period	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 366 of file stk_c_time.cpp.

{
    STK_ASSERT(trig != nullptr);
 
    trig->handle.SetPeriod(static_cast<Ticks>(period));
}

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

Here is the call graph for this function: