stk_c_time.h File Reference

C language binding for stk::time::TimerHost and stk::time::TimerHost::Timer. More...

#include "stk_c.h"

Include dependency graph for stk_c_time.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Macros
#define	STK_C_TIMER_MAX   32
	Maximum number of concurrent stk_timer_t instances per core (default: 32).
#define	STK_C_TIMER_HANDLER_STACK_SIZE   256
	Stack size of the timer handler, increase if your timers consume more (default: 256).
#define	STK_PERIODIC_TRIGGER_IMPL_SIZE   16
	A memory size (multiples of size_t) required for PeriodicTrigger instance.

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.
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_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 *timer)
	Return a timer handle back to the static pool.
bool	stk_timer_start (stk_timerhost_t *host, stk_timer_t *timer, uint32_t delay, uint32_t period)
	Start a timer.
bool	stk_timer_stop (stk_timerhost_t *host, stk_timer_t *timer)
	Stop a running timer.
bool	stk_timer_reset (stk_timerhost_t *host, stk_timer_t *timer)
	Reset a periodic timer's deadline (re-arm from now).
bool	stk_timer_restart (stk_timerhost_t *host, stk_timer_t *timer, 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 *timer, uint32_t delay, uint32_t period)
	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 *timer, uint32_t period)
	Change the period of a running periodic timer without affecting the current deadline.
bool	stk_timer_is_active (const stk_timer_t *timer)
	Check whether a timer is currently active (started and not yet expired/stopped).
uint32_t	stk_timer_get_period (const stk_timer_t *timer)
	Get the timer's reload period.
int64_t	stk_timer_get_deadline (const stk_timer_t *timer)
	Get the absolute expiration tick count of the timer's next deadline.
int64_t	stk_timer_get_timestamp (const stk_timer_t *timer)
	Get the tick count at which the timer last expired.
uint32_t	stk_timer_get_remaining_time (const stk_timer_t *timer)
	Get remaining ticks until next expiration.
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

C language binding for stk::time::TimerHost and stk::time::TimerHost::Timer.

One stk_timerhost_t instance is pre-allocated per CPU core (up to STK_C_CPU_COUNT cores). Obtain a handle for a given core with stk_timerhost_get() before calling any other timer API.

Concrete timers (stk_timer_t) are allocated from a fixed-size static pool of STK_C_TIMER_MAX slots shared across all cores. Each timer stores a user callback (stk_timer_callback_t) and an opaque user data pointer that are forwarded when the timer expires.

Definition in file stk_c_time.h.