EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:

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_error_t etcpal_init(etcpal_features_t features)
Initialize the EtcPal library.
Definition: common.c:87
#define ETCPAL_FEATURE_TIMERS
Use the etcpal/timer module.
Definition: common.h:129

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();
uint32_t etcpal_getms(void)
Get a monotonically-increasing millisecond value.

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);
#define ETCPAL_TIME_ELAPSED_SINCE(start_time)
Get the amount of time elapsed since the given time point in milliseconds.
Definition: timer.h:112

To time an interval, use an EtcPalTimer.

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.
uint32_t etcpal_timer_elapsed(const EtcPalTimer *timer)
Get the time since a timer was reset.
Definition: timer.c:56
void etcpal_timer_start(EtcPalTimer *timer, uint32_t interval)
Start a timer.
Definition: timer.c:30
uint32_t etcpal_timer_remaining(const EtcPalTimer *timer)
Get the amount of time remaining in a timer.
Definition: timer.c:87
bool etcpal_timer_is_expired(const EtcPalTimer *timer)
Check to see if a timer is expired.
Definition: timer.c:73
void etcpal_timer_reset(EtcPalTimer *timer)
Reset a timer while keeping the same interval.
Definition: timer.c:43
A millisecond-resolution timer.
Definition: timer.h:102

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
timerPointer 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
timerPointer 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
timerPointer 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
timerPointer to the EtcPalTimer to reset.

◆ etcpal_timer_start()

void etcpal_timer_start ( EtcPalTimer timer,
uint32_t  interval 
)

Start a timer.

Parameters
timerPointer to the EtcPalTimer to start.
intervalTimer interval in milliseconds. An interval of 0 will result in a timer that is always expired.