pw::chrono::SystemTimer Class Reference

#include <system_timer.h>

Public Types
using	native_handle_type = backend::NativeSystemTimerHandle
using	ExpiryCallback = Function< void(SystemClock::time_point expired_deadline)>

Public Member Functions
	SystemTimer (ExpiryCallback &&callback)
	~SystemTimer ()
	SystemTimer (const SystemTimer &)=delete
	SystemTimer (SystemTimer &&)=delete
SystemTimer &	operator= (const SystemTimer &)=delete
SystemTimer &	operator= (SystemTimer &&)=delete
void	InvokeAfter (SystemClock::duration delay)
void	InvokeAt (SystemClock::time_point timestamp)
void	Cancel ()
native_handle_type	native_handle ()

Detailed Description

The SystemTimer allows an ExpiryCallback be executed at a set time in the future.

The base SystemTimer only supports a one-shot style timer with a callback. A periodic timer can be implemented by rescheduling the timer in the callback through InvokeAt(kDesiredPeriod + expired_deadline).

When implementing a periodic layer on top, the user should be mindful of handling missed periodic callbacks. They could opt to invoke the callback multiple times with the expected expired_deadline values or instead saturate and invoke the callback only once with the latest expired_deadline.

The entire API is thread safe, however it is NOT always IRQ safe.

Member Typedef Documentation

ExpiryCallback

using pw::chrono::SystemTimer::ExpiryCallback = Function<void(SystemClock::time_point expired_deadline)>

The ExpiryCallback is either invoked from a high priority thread or an interrupt.

For a given timer instance, its ExpiryCallback will not preempt itself. This makes it appear like there is a single executor of a timer instance's ExpiryCallback.

Ergo ExpiryCallbacks should be treated as if they are executed by an interrupt, meaning:

• Processing inside of the callback should be kept to a minimum.
• Callbacks should never attempt to block.
• APIs which are not interrupt safe such as pw::sync::Mutex should not be used!

Constructor & Destructor Documentation

SystemTimer()

pw::chrono::SystemTimer::SystemTimer

(

ExpiryCallback &&

callback

)

Constructs the SystemTimer based on the user provided pw::Function<void(SystemClock::time_point expired_deadline)>. Note that The ExpiryCallback is either invoked from a high priority thread or an interrupt.

~SystemTimer()

pw::chrono::SystemTimer::~SystemTimer

(

)

Cancels the timer and blocks if necssary if the callback is already being processed.

Postcondition: The expiry callback is not in progress and will not be called in the future.

Member Function Documentation

Cancel()

void pw::chrono::SystemTimer::Cancel

(

)

Cancels the software timer expiry callback if pending.

Canceling a timer which isn't scheduled does nothing.

If the callback is already being executed while you cancel it, it will finish callback execution to completion. You are responsible for any synchronization which is needed for thread safety.

This is thread safe, it may not be IRQ safe.

InvokeAfter()

void pw::chrono::SystemTimer::InvokeAfter

(

SystemClock::duration

delay

)

Invokes the expiry callback as soon as possible after at least the specified duration.

Scheduling a callback cancels the existing callback (if pending). If the callback is already being executed while you reschedule it, it will finish callback execution to completion. You are responsible for any critical section locks which may be needed for timer coordination.

This is thread safe, it may not be IRQ safe.

InvokeAt()

void pw::chrono::SystemTimer::InvokeAt

(

SystemClock::time_point

timestamp

)

Invokes the expiry callback as soon as possible starting at the specified time_point.

Scheduling a callback cancels the existing callback (if pending). If the callback is already being executed while you reschedule it, it will finish callback execution to completion. You are responsible for any critical section locks which may be needed for timer coordination.

This is thread safe, it may not be IRQ safe.

---

The documentation for this class was generated from the following file:

• pw_chrono/public/pw_chrono/system_timer.h