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 C Timer Synchronous API

Blocking variants of the timer control functions. More...

Collaboration diagram for STK C Timer Synchronous API:

Functions

stk_timer_result_t stk_timer_start_sync (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
 Start a timer and wait for the result.
stk_timer_result_t stk_timer_activate_sync (stk_timerhost_t *host, stk_timer_t *tmr)
 Start a timer with the delay and period stored in it and wait for the result.
stk_timer_result_t stk_timer_stop_sync (stk_timerhost_t *host, stk_timer_t *tmr)
 Stop a timer and wait for the result.
stk_timer_result_t stk_timer_restart_sync (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
 Atomically stop and re-start a timer and wait for the result.
stk_timer_result_t stk_timer_reset_sync (stk_timerhost_t *host, stk_timer_t *tmr)
 Reset a periodic timer's deadline (re-arm from now) and wait for the result.
stk_timer_result_t stk_timer_set_period_sync (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 and wait for the result.
stk_timer_result_t stk_timer_change_sync (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
 Change the delay and period of an inactive timer and wait for the result.
stk_timer_result_t stk_timer_query_sync (stk_timerhost_t *host, stk_timer_t *tmr, stk_timer_info_t *info)
 Get a consistent snapshot of a timer (evaluated by the tick task).

Detailed Description

Blocking variants of the timer control functions.

The asynchronous functions above only queue a request and report whether it was accepted. The functions below queue the same command together with a completion point and block the caller until the tick task has executed it, so the result is the exact outcome of the command (e.g. STK_TIMER_RES_ACTIVE for a timer which was already active).

Note
A call waits only where waiting is possible: task context, kernel running, task mode. From an ISR, before the kernel is started, or in polled mode the command is queued asynchronously and STK_TIMER_RES_QUEUED is returned (STK_TIMER_RES_QUEUE_FULL if the queue is full).
A sync call blocks while the command queue is full instead of failing (see STK_C_TIMER_COMMAND_QUEUE_MAX).
The tick task must be at least as urgent as every task which uses this API, see stk_timerhost_config_t (weights).
Callbacks may use this API in task mode (they run in handler tasks).

Function Documentation

◆ stk_timer_activate_sync()

stk_timer_result_t stk_timer_activate_sync ( stk_timerhost_t * host,
stk_timer_t * tmr )

Start a timer with the delay and period stored in it and wait for the result.

Parameters
[in]hostTimerHost that will manage this timer.
[in]tmrTimer handle. Must not be active.
Returns
As stk_timer_start_sync().
Note
The parameters are those of the last start, restart or stk_timer_change_sync(), the expiration is relative to the moment of the call.

Definition at line 351 of file stk_c_time.cpp.

352{
353 STK_ASSERT(host != nullptr);
354 STK_ASSERT(tmr != nullptr);
355
356 // refresh host association before timer can fire
357 tmr->SetHostHandle(host);
358
359 return ToCTimerResult(host->handle.ActivateSync(*tmr));
360}
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
EResult ActivateSync(Timer &tmr)
Start timer with the delay and period stored in it and wait for the result.
void SetHostHandle(stk_timerhost_t *host_handle)
TimerHost handle

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

Here is the call graph for this function:

◆ stk_timer_change_sync()

stk_timer_result_t stk_timer_change_sync ( stk_timerhost_t * host,
stk_timer_t * tmr,
uint32_t delay,
uint32_t period )

Change the delay and period of an inactive timer and wait for the result.

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle. Must not be active.
[in]delayNew initial delay in ticks.
[in]periodNew reload period in ticks, 0 for a one-shot timer.
Returns
STK_TIMER_RES_OK, STK_TIMER_RES_ACTIVE if the timer is active (nothing is changed), STK_TIMER_RES_QUEUED, or an error (STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, STK_TIMER_RES_CANCELLED).
Note
The timer is not started, the values are used by the next stk_timer_activate_sync().

Definition at line 397 of file stk_c_time.cpp.

398{
399 STK_ASSERT(host != nullptr);
400 STK_ASSERT(tmr != nullptr);
401
402 // refresh host association before timer can fire
403 tmr->SetHostHandle(host);
404
405 return ToCTimerResult(host->handle.ChangeSync(*tmr, delay, period));
406}
EResult ChangeSync(Timer &tmr, uint32_t delay, uint32_t period)
Change the delay and period of an inactive timer and wait for the result.

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

Here is the call graph for this function:

◆ stk_timer_query_sync()

stk_timer_result_t stk_timer_query_sync ( stk_timerhost_t * host,
stk_timer_t * tmr,
stk_timer_info_t * info )

Get a consistent snapshot of a timer (evaluated by the tick task).

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle.
[out]infoSnapshot, valid if the result is STK_TIMER_RES_OK.
Returns
STK_TIMER_RES_OK, or STK_TIMER_RES_NOT_READY if the host is not initialized or has been shut down.
Note
From a context which can not wait the snapshot is read without synchronization and is advisory (STK_TIMER_RES_OK is returned).

Definition at line 408 of file stk_c_time.cpp.

409{
410 STK_ASSERT(host != nullptr);
411 STK_ASSERT(tmr != nullptr);
412 STK_ASSERT(info != nullptr);
413
414 TimerHost::TimerInfo ti = {};
415 const TimerHost::EResult res = host->handle.QuerySync(*tmr, ti);
416
417 if (res == TimerHost::RES_OK)
418 {
419 info->active = ti.active;
420 info->remaining = ti.remaining;
421 info->delay = ti.delay;
422 info->period = ti.period;
423 }
424
425 return ToCTimerResult(res);
426}
EResult QuerySync(Timer &tmr, TimerInfo &info)
Get a consistent snapshot of the timer (evaluated by the tick task).
EResult
Outcome of a command: returned by the asynchronous API (Start(), Stop(), ...) and by the synchronous ...
@ RES_OK
Sync: the command was executed. Async: the command was accepted into the command queue.
Consistent snapshot of a timer, see QuerySync().
uint32_t delay
Initial delay stored by Start(), Restart(), ChangeSync().
uint32_t remaining
Ticks until the next expiration, 0 if not active or overdue.
uint32_t period
Reload period, 0 for a one-shot timer.
bool active
True if the timer is active.
uint32_t delay
Initial delay stored by the last start / restart / change.
Definition stk_c_time.h:394
uint32_t remaining
Ticks until the next expiration, 0 if not active or overdue.
Definition stk_c_time.h:393
bool active
true if the timer is active.
Definition stk_c_time.h:392
uint32_t period
Reload period in ticks, 0 for a one-shot timer.
Definition stk_c_time.h:395

References stk::time::TimerHost::TimerInfo::active, stk_timer_info_t::active, stk::time::TimerHost::TimerInfo::delay, stk_timer_info_t::delay, stk_timerhost_t::handle, stk::time::TimerHost::TimerInfo::period, stk_timer_info_t::period, stk::time::TimerHost::QuerySync(), stk::time::TimerHost::TimerInfo::remaining, stk_timer_info_t::remaining, stk::time::TimerHost::RES_OK, and STK_ASSERT.

Here is the call graph for this function:

◆ stk_timer_reset_sync()

stk_timer_result_t stk_timer_reset_sync ( stk_timerhost_t * host,
stk_timer_t * tmr )

Reset a periodic timer's deadline (re-arm from now) and wait for the result.

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle. Must be active and periodic.
Returns
STK_TIMER_RES_OK, STK_TIMER_RES_INACTIVE, STK_TIMER_RES_NOT_PERIODIC, STK_TIMER_RES_QUEUED, or an error (STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, STK_TIMER_RES_CANCELLED).

Definition at line 381 of file stk_c_time.cpp.

382{
383 STK_ASSERT(host != nullptr);
384 STK_ASSERT(tmr != nullptr);
385
386 return ToCTimerResult(host->handle.ResetSync(*tmr));
387}
EResult ResetSync(Timer &tmr)
Reset periodic timer's deadline and wait for the result.

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

Here is the call graph for this function:

◆ stk_timer_restart_sync()

stk_timer_result_t stk_timer_restart_sync ( stk_timerhost_t * host,
stk_timer_t * tmr,
uint32_t delay,
uint32_t period )

Atomically stop and re-start a timer and wait for the result.

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle (active or inactive).
[in]delayInitial delay in ticks before the first expiration (stored in the timer).
[in]periodReload period in ticks, 0 for a one-shot timer (stored in the timer).
Returns
STK_TIMER_RES_OK, STK_TIMER_RES_QUEUED, or an error (STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, STK_TIMER_RES_CANCELLED).

Definition at line 370 of file stk_c_time.cpp.

371{
372 STK_ASSERT(host != nullptr);
373 STK_ASSERT(tmr != nullptr);
374
375 // refresh host association before timer can fire
376 tmr->SetHostHandle(host);
377
378 return ToCTimerResult(host->handle.RestartSync(*tmr, delay, period));
379}
EResult RestartSync(Timer &tmr, uint32_t delay, uint32_t period=0)
Atomically stop and re-start timer and wait for the result.

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

Here is the call graph for this function:

◆ stk_timer_set_period_sync()

stk_timer_result_t stk_timer_set_period_sync ( 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 and wait for the result.

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle. Must be active and periodic.
[in]period_ticksNew reload period in ticks. Must be non-zero.
Returns
STK_TIMER_RES_OK, STK_TIMER_RES_INACTIVE or STK_TIMER_RES_NOT_PERIODIC (nothing is changed), STK_TIMER_RES_INVALID_PARAM (zero or too large period, nothing is queued), STK_TIMER_RES_QUEUED, or an error (STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, STK_TIMER_RES_CANCELLED).
Note
Unlike stk_timer_set_period() the state is evaluated by the tick task, so the outcome is exact. The new period takes effect on the next reload, follow with stk_timer_reset_sync() to apply it immediately.

Definition at line 389 of file stk_c_time.cpp.

390{
391 STK_ASSERT(host != nullptr);
392 STK_ASSERT(tmr != nullptr);
393
394 return ToCTimerResult(host->handle.SetPeriodSync(*tmr, period_ticks));
395}
EResult SetPeriodSync(Timer &tmr, uint32_t period)
Change the period of a running periodic timer without affecting its current deadline and wait for the...

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

Here is the call graph for this function:

◆ stk_timer_start_sync()

stk_timer_result_t stk_timer_start_sync ( stk_timerhost_t * host,
stk_timer_t * tmr,
uint32_t delay,
uint32_t period )

Start a timer and wait for the result.

Parameters
[in]hostTimerHost that will manage this timer.
[in]tmrTimer handle. Must not be active.
[in]delayInitial delay in ticks before the first expiration (stored in the timer).
[in]periodReload period in ticks, 0 for a one-shot timer (stored in the timer).
Returns
STK_TIMER_RES_OK if started, STK_TIMER_RES_ACTIVE if already active (nothing is changed), STK_TIMER_RES_QUEUED, or an error (STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, STK_TIMER_RES_CANCELLED).

Definition at line 337 of file stk_c_time.cpp.

341{
342 STK_ASSERT(host != nullptr);
343 STK_ASSERT(tmr != nullptr);
344
345 // refresh host association before timer can fire
346 tmr->SetHostHandle(host);
347
348 return ToCTimerResult(host->handle.StartSync(*tmr, delay, period));
349}
EResult StartSync(Timer &tmr, uint32_t delay, uint32_t period=0)
Start timer and wait for the result (see "Synchronous API" in TimerHost).

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

Here is the call graph for this function:

◆ stk_timer_stop_sync()

stk_timer_result_t stk_timer_stop_sync ( stk_timerhost_t * host,
stk_timer_t * tmr )

Stop a timer and wait for the result.

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle.
Returns
STK_TIMER_RES_OK if it was active, STK_TIMER_RES_INACTIVE if it was not (e.g. a one-shot which already expired; its queued callback is cancelled if it has not started yet), STK_TIMER_RES_QUEUED, or an error (STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, STK_TIMER_RES_CANCELLED).
Note
Also waits until a callback of this timer which a handler task has already started has returned: after STK_TIMER_RES_OK / STK_TIMER_RES_INACTIVE the host holds no reference to the timer and its memory (stk_timer_mem_t) may be released, see stk_timer_destroy().
Warning
Called from a timer callback it does not wait for running callbacks (deadlock guard): it only guarantees that no further callback of the timer starts. Do not release the timer from a callback of another timer.

Definition at line 362 of file stk_c_time.cpp.

363{
364 STK_ASSERT(host != nullptr);
365 STK_ASSERT(tmr != nullptr);
366
367 return ToCTimerResult(host->handle.StopSync(*tmr));
368}
EResult StopSync(Timer &tmr)
Stop timer and wait for the result.

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

Here is the call graph for this function: