pw_chrono

Oveview

Portable std::chrono for constrained embedded devices. Main docs: https://pigweed.dev/pw_chrono.

Classes
struct	pw::chrono::SystemClock
class	pw::chrono::VirtualClock< SystemClock >
class	pw::chrono::SystemTimer
class	pw::chrono::VirtualClock< Clock >

Typedefs
using	pw::chrono::SystemClock::rep = int64_t
using	pw::chrono::SystemClock::period = std::ratio< PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_NUMERATOR, PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_DENOMINATOR >
	The period must be provided by the backend.
using	pw::chrono::SystemClock::duration = std::chrono::duration< rep, period >
	Alias for durations representable with this clock.
using	pw::chrono::SystemClock::time_point = std::chrono::time_point< SystemClock >
using	pw::chrono::VirtualSystemClock = VirtualClock< SystemClock >
using	pw::chrono::SystemTimer::native_handle_type = backend::NativeSystemTimerHandle
using	pw::chrono::SystemTimer::ExpiryCallback = Function< void(SystemClock::time_point expired_deadline)>

Functions
int64_t	pw::chrono::backend::GetSystemClockTickCount ()
static time_point	pw::chrono::SystemClock::now () noexcept
	This is thread and IRQ safe. This must be provided by the backend.
template<class Rep , class Period >
static constexpr duration	pw::chrono::SystemClock::for_at_least (std::chrono::duration< Rep, Period > d)
static time_point	pw::chrono::SystemClock::TimePointAfterAtLeast (duration after_at_least)
static VirtualClock< SystemClock > &	pw::chrono::VirtualClock< SystemClock >::RealClock ()
	Returns a reference to the real system clock to aid instantiation.
virtual SystemClock::time_point	pw::chrono::VirtualClock< SystemClock >::now ()=0
	Returns the current time.
	pw::chrono::SystemTimer::SystemTimer (ExpiryCallback &&callback)
	pw::chrono::SystemTimer::~SystemTimer ()
	pw::chrono::SystemTimer::SystemTimer (const SystemTimer &)=delete
	pw::chrono::SystemTimer::SystemTimer (SystemTimer &&)=delete
SystemTimer &	pw::chrono::SystemTimer::operator= (const SystemTimer &)=delete
SystemTimer &	pw::chrono::SystemTimer::operator= (SystemTimer &&)=delete
void	pw::chrono::SystemTimer::InvokeAfter (SystemClock::duration delay)
void	pw::chrono::SystemTimer::InvokeAt (SystemClock::time_point timestamp)
void	pw::chrono::SystemTimer::Cancel ()
native_handle_type	pw::chrono::SystemTimer::native_handle ()
virtual Clock::time_point	pw::chrono::VirtualClock< Clock >::now ()=0
	Returns the current time.

Variables
static constexpr Epoch	pw::chrono::SystemClock::epoch = backend::kSystemClockEpoch
	The epoch must be provided by the backend.
static constexpr bool	pw::chrono::SystemClock::is_monotonic = true
static constexpr bool	pw::chrono::SystemClock::is_steady = false
static constexpr bool	pw::chrono::SystemClock::is_free_running = backend::kSystemClockFreeRunning
static constexpr bool	pw::chrono::SystemClock::is_stopped_in_halting_debug_mode = true
	The clock must stop while in halting debug mode.
static constexpr bool	pw::chrono::SystemClock::is_always_enabled = true
	The now() function can be invoked at any time.
static constexpr bool	pw::chrono::SystemClock::is_nmi_safe = backend::kSystemClockNmiSafe
int64_t	pw_chrono_SystemClock_Duration::ticks
pw_chrono_SystemClock_Duration	pw_chrono_SystemClock_TimePoint::duration_since_epoch

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!

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.

for_at_least()

template<class Rep , class Period >

static constexpr duration pw::chrono::SystemClock::for_at_least ( std::chrono::duration< Rep, Period >  d )

inlinestaticconstexpr

This is purely a helper, identical to directly using std::chrono::ceil, to convert a duration type which cannot be implicitly converted where the result is rounded up.

GetSystemClockTickCount()

int64_t pw::chrono::backend::GetSystemClockTickCount

(

)

The ARM AEBI does not permit the opaque 'time_point' to be passed via registers, ergo the underlying fundamental type is forward declared. A SystemCLock tick has the units of one SystemClock::period duration. This must be thread and IRQ safe and provided by the backend.

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.

now() [1/2]

virtual SystemClock::time_point pw::chrono::VirtualClock< SystemClock >::now ( )

pure virtual

Returns the current time.

Implemented in pw::async::HeapDispatcher, pw::async::BasicDispatcher, and pw::chrono::SimulatedSystemClock.

now() [2/2]

template<typename Clock >

virtual Clock::time_point pw::chrono::VirtualClock< Clock >::now ( )

pure virtual

Returns the current time.

Implemented in pw::async2::SimulatedTimeProvider< Clock >, and pw::async2::TimeProvider< Clock >.

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.

TimePointAfterAtLeast()

static time_point pw::chrono::SystemClock::TimePointAfterAtLeast ( duration  after_at_least )

inlinestatic

Computes the nearest time_point after the specified duration has elapsed.

This is useful for translating delay or timeout durations into deadlines.

The time_point is computed based on now() plus the specified duration where a singular clock tick is added to handle partial ticks. This ensures that a duration of at least 1 tick does not result in [0,1] ticks and instead in [1,2] ticks.

~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.

Variable Documentation

is_free_running

constexpr bool pw::chrono::SystemClock::is_free_running = backend::kSystemClockFreeRunning

staticconstexpr

The now() function may not move forward while in a critical section or interrupt. This must be provided by the backend.

is_monotonic

constexpr bool pw::chrono::SystemClock::is_monotonic = true

staticconstexpr

The time points of this clock cannot decrease, however the time between ticks of this clock may slightly vary due to sleep modes. The duration during sleep may be ignored or backfilled with another clock.

is_nmi_safe

constexpr bool pw::chrono::SystemClock::is_nmi_safe = backend::kSystemClockNmiSafe

staticconstexpr

The now() function may work in non-maskable interrupt contexts (e.g. exception/fault handlers), depending on the backend. This must be provided by the backend.