periodic.h File Reference

Periodic ztimer API. More...

Detailed Description

Periodic ztimer API.

Once started, the periodic timer will call the configured callback function once each interval until the timer is either stopped using ztimer_periodic_stop or the callback function returns a non-zero value.

Should the timer underflow ((time_at_interrupt + interval) % 2**32 > interval), the next timer will be scheduled with an offset of zero, thus fire right away. This leads to a callback for each missed tick, until the original period can be honoured again.

Example:

#include "ztimer/periodic.h"
 
static bool callback(void *arg)
{
   puts(arg);
 
   // keep the timer running
   return true;
}
 
 
int main(void)
{
    // allocate timer in .bss with static, so that timer can keep
    // running when leaving function scope
    static ztimer_periodic_t timer;
    // initialize timer
    ztimer_periodic_init(ZTIMER_SEC, &timer, callback, "test", 1);
 
    // start timer
    ztimer_periodic_start(&timer);
    // timer will tick every 1 second
 
    // call again to reset timer (will abort current period and trigger next
    // after full interval)
    ztimer_periodic_start(&timer);
 
    // stop timer (will not trigger anymore)
    ztimer_periodic_stop(&timer);
 
    // NOTE: if using a stack allocated timer, *it must be stopped before
    //       going out of scope*!
}

ztimer periodic API

Author

Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Definition in file periodic.h.

#include <stdbool.h>
#include <stdint.h>
#include "ztimer.h"

Include dependency graph for periodic.h:

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

Go to the source code of this file.

Data Structures
struct	ztimer_periodic_t
	ztimer periodic structure More...
#define	ZTIMER_PERIODIC_KEEP_GOING   true
	Periodic timer stop unless it returns this value.
typedef bool(*	ztimer_periodic_callback_t) (void *)
	Type of callbacks in periodic timers.
void	ztimer_periodic_init (ztimer_clock_t *clock, ztimer_periodic_t *timer, bool(*callback)(void *), void *arg, uint32_t interval)
	Initialize a periodic timer structure.
void	ztimer_periodic_start (ztimer_periodic_t *timer)
	Start or restart a periodic timer.
void	ztimer_periodic_stop (ztimer_periodic_t *timer)
	Stop a periodic timer.

Macro Definition Documentation

ZTIMER_PERIODIC_KEEP_GOING

#define ZTIMER_PERIODIC_KEEP_GOING   true

Periodic timer stop unless it returns this value.

Definition at line 84 of file periodic.h.

Typedef Documentation

ztimer_periodic_callback_t

typedef bool(* ztimer_periodic_callback_t) (void *)

Type of callbacks in periodic timers.

Definition at line 89 of file periodic.h.

Function Documentation

ztimer_periodic_init()

void ztimer_periodic_init	(	ztimer_clock_t *	clock,
		ztimer_periodic_t *	timer,
		bool(*)(void *)	callback,
		void *	arg,
		uint32_t	interval
	)

Initialize a periodic timer structure.

This sets up the underlying structure of a periodic timer. After initializing, use ztimer_periodic_start() to start the timer.

Parameters

[in]	clock	the clock to configure this timer on
[in,out]	timer	periodic timer object to initialize
[in]	callback	function to call on each trigger returns true if the timer should keep going
[in]	arg	argument to pass to callback function
[in]	interval	period length of this timer instance

ztimer_periodic_start()

void ztimer_periodic_start

(

ztimer_periodic_t *

timer

)

Start or restart a periodic timer.

When called on a newly initialized timer, the timer will start.

When called on an already running timer, the current interval is reset to its start (thus the next callback will be called after the configured interval has passed).

Parameters

[in]

timer

periodic timer object to work on

ztimer_periodic_stop()

void ztimer_periodic_stop

(

ztimer_periodic_t *

timer

)

Stop a periodic timer.

The periodic timer will not trigger anymore.

Parameters

[in]

timer

periodic timer object to stop