timer (Timers)

Overview

Platform-neutral system timers.

#include "etcpal/timer.h"

WARNING: This module must be explicitly initialized before use. Initialize the module by calling etcpal_init() with the relevant feature mask:

etcpal_init(ETCPAL_FEATURE_TIMERS);

Provides an implementation of a passive monotonic timer, as well as a way to get monotonic time points. Time points and intervals are represented in milliseconds by a 32-bit unsigned int. To get a time point, use etcpal_getms().

uint32_t time_point = etcpal_getms();

A time point represents the time elapsed in milliseconds since an arbitrary fixed point in the past, independent of any changes in system "wall clock" time. Time points provided by this module wrap every 4,294,967,295 milliseconds, or approximately 49.7 days. Because of this, it's recommended to only use this module to time events which occur on time scales which are shorter than that by at least an order of magnitude. This reduces the likelihood that wrapping will be an issue.

Note that this problem only applies to wraparound past an original time point; absolute wraparound of the integer type is handled. For example, using an EtcPalTimer to time a 10-millisecond interval that begins at time point 4,294,967,290 and ends at time point 5 will work as expected.

Use the ETCPAL_TIME_ELAPSED_SINCE() macro to determine how much time has elapsed since a time point.

uint32_t ms_elapsed = ETCPAL_TIME_ELAPSED_SINCE(time_point);

To time an interval, use an EtcPalTimer.

EtcPalTimer timer;
etcpal_timer_start(&timer, 100); // Start a 100-millisecond timer
 
// Some time later...
 
uint32_t elapsed = etcpal_timer_elapsed(&timer); // How many milliseconds since the timer was started
uint32_t remaining = etcpal_timer_remaining(&timer); // How much time is remaining in the interval
bool is_expired = etcpal_timer_is_expired(&timer); // Whether the interval has expired
 
etcpal_timer_reset(&timer); // Reset the timer for another 100-millisecond interval
// Or
etcpal_timer_start(&timer, 1000); // Reuse the timer for a different interval, in this case 1 second.

Data Structures
struct	EtcPalTimer
	A millisecond-resolution timer. More...

Macros
#define	ETCPAL_TIME_ELAPSED_SINCE(start_time)   (uint32_t)(etcpal_getms() - (uint32_t)start_time)
	Get the amount of time elapsed since the given time point in milliseconds. More...

Typedefs
typedef struct EtcPalTimer	EtcPalTimer
	A millisecond-resolution timer. More...

Functions
uint32_t	etcpal_getms (void)
	Get a monotonically-increasing millisecond value. More...
void	etcpal_timer_start (EtcPalTimer *timer, uint32_t interval)
	Start a timer. More...
void	etcpal_timer_reset (EtcPalTimer *timer)
	Reset a timer while keeping the same interval. More...
uint32_t	etcpal_timer_elapsed (const EtcPalTimer *timer)
	Get the time since a timer was reset. More...
bool	etcpal_timer_is_expired (const EtcPalTimer *timer)
	Check to see if a timer is expired. More...
uint32_t	etcpal_timer_remaining (const EtcPalTimer *timer)
	Get the amount of time remaining in a timer. More...

Macro Definition Documentation

ETCPAL_TIME_ELAPSED_SINCE

#define ETCPAL_TIME_ELAPSED_SINCE

(

start_time

)

(uint32_t)(etcpal_getms() - (uint32_t)start_time)

Get the amount of time elapsed since the given time point in milliseconds.

Parameters

start_time

(uint32_t) The start time to measure against.

Returns

The number of milliseconds elapsed since the start time.

Typedef Documentation

EtcPalTimer

typedef struct EtcPalTimer EtcPalTimer

A millisecond-resolution timer.

The times are represented in milliseconds by a 32-bit unsigned integer. Since the timer is monotonically-increasing, wraparound is handled by doing comparisons of the form

timeA - timeB > 0 

rather than

timeA > timeB 

.

Function Documentation

etcpal_getms()

uint32_t etcpal_getms

(

void

)

Get a monotonically-increasing millisecond value.

Returns

The current timestamp in milliseconds.

etcpal_timer_elapsed()

uint32_t etcpal_timer_elapsed

(

const EtcPalTimer *

timer

)

Get the time since a timer was reset.

Parameters

timer

Pointer to the EtcPalTimer of which to get the elapsed time.

Returns

Number of milliseconds since the timer was reset.

etcpal_timer_is_expired()

bool etcpal_timer_is_expired

(

const EtcPalTimer *

timer

)

Check to see if a timer is expired.

Parameters

timer

Pointer to the EtcPalTimer of which to check the expiration.

Returns

true: More than interval milliseconds have passed since the timer was started/reset.

false: Less than or equal to interval milliseconds have passed since the timer was started/reset)

etcpal_timer_remaining()

uint32_t etcpal_timer_remaining

(

const EtcPalTimer *

timer

)

Get the amount of time remaining in a timer.

Parameters

timer

Pointer to the EtcPalTimer of which to get the remaining time.

Returns

Remaining time in milliseconds or 0 (timer is expired).

etcpal_timer_reset()

void etcpal_timer_reset

(

EtcPalTimer *

timer

)

Reset a timer while keeping the same interval.

Parameters

timer

Pointer to the EtcPalTimer to reset.

etcpal_timer_start()

void etcpal_timer_start	(	EtcPalTimer *	timer,
		uint32_t	interval
	)

Start a timer.

Parameters

timer	Pointer to the EtcPalTimer to start.
interval	Timer interval in milliseconds. An interval of 0 will result in a timer that is always expired.