Cpl::System::PeriodicScheduler Class Reference

This concrete class is a 'policy' object that is used to add polled based, cooperative monotonic scheduling to a Runnable object. More...

Detailed Description

This concrete class is a 'policy' object that is used to add polled based, cooperative monotonic scheduling to a Runnable object.

Monotonic in this content means that if a 'interval' method is scheduled to execute at a periodic rate of 200Hz, then the method will be called on every 5ms boundary of the system time.

The scheduler makes its best attempt at being monotonic and deterministic, BUT because the scheduling is polled and cooperative (i.e. its is the application's responsibility to not-overrun/over-allocate the processing done during each interval) the actual the timing cannot be guaranteed. That said, the scheduler will detect and report when the interval timing slips.

The usage of this class is to implement (or extended) a Cpl::System::Runnable object, i.e. invoked inside the 'forever' loop of the Runnable object's appRun() method. The scheduler can be use within a 'bare' forever loop and it can be used with existing event based Runnable objects to add periodic scheduling. See Cpl::Dm::PeriodicScheduler for example extending an event based Runnable object to include periodic scheduling.

#include <PeriodicScheduler.h>

Inheritance diagram for Cpl::System::PeriodicScheduler:

Collaboration diagram for Cpl::System::PeriodicScheduler:

Classes
struct	Interval_T
	Defines an interval. More...

Public Types
typedef void(*	IntervalCallbackFunc_T) (ElapsedTime::Precision_T currentTick, ElapsedTime::Precision_T currentInterval, void *context)
	Definition for an interval method.
typedef void(*	ReportSlippageFunc_T) (Interval_T &intervalThatSlipped, ElapsedTime::Precision_T currentTick, ElapsedTime::Precision_T missedInterval)
	Defines the method that is used to report to the Application when an Interval does not execute 'on time'.
typedef ElapsedTime::Precision_T(*	NowFunc_T) ()
	Defines the function that returns current system.
typedef void(*	Hook_T) (ElapsedTime::Precision_T currentTick)
	Defines the optional functions that are used to provide hooks during startup/shutdown of the thread/loop[ to perform application specific processing.

Public Member Functions
	PeriodicScheduler (Interval_T intervals[], Hook_T beginThreadProcessing=nullptr, Hook_T endThreadProcessing=nullptr, ReportSlippageFunc_T slippageFunc=nullptr, NowFunc_T nowFunc=ElapsedTime::precision)
	Constructor.
virtual	~PeriodicScheduler ()
	Virtual destructor.
virtual bool	executeScheduler ()
	This method is used to invoke the scheduler.
virtual void	beginLoop ()
	This method is expected to be called ONCE when the 'thread' is started and prior to the thread entering its 'forever' loop.
virtual void	endLoop ()
	This method is expected to be called ONCE when the 'thread' has exited its 'forever' loop (but before the thread has actually terminated)

Protected Member Functions
void	setTimeMarker (Interval_T &interval, ElapsedTime::Precision_T currentTick) noexcept
	Helper method to Round DOWN to the nearest 'interval' boundary.

Protected Attributes
Interval_T *	m_intervals
	List of Intervals Pointers.
ReportSlippageFunc_T	m_reportSlippage
	Report slippage method.
NowFunc_T	m_nowFunc
	Current system callback.
Hook_T	m_beginThreadFunc
	Application hook during thread start-up.
Hook_T	m_endThreadFunc
	Application hook during thread shutdown.
bool	m_firstExecution
	Flag to managing the 'first' execution.

Member Typedef Documentation

Hook_T

typedef void(* Cpl::System::PeriodicScheduler::Hook_T) (ElapsedTime::Precision_T currentTick)

Defines the optional functions that are used to provide hooks during startup/shutdown of the thread/loop[ to perform application specific processing.

IntervalCallbackFunc_T

typedef void(* Cpl::System::PeriodicScheduler::IntervalCallbackFunc_T) (ElapsedTime::Precision_T currentTick, ElapsedTime::Precision_T currentInterval, void *context)

Definition for an interval method.

This method is called when the period time has expired for the interval.

Where: currentTick - is current system when the interval method is called currentInterval - is the deterministic interval boundary that is being logically executed. context - Application defined argument/value passed to the interval method.

Example: Given a interval method is scheduled to execute at 10Hz and the current system time in the Runnable object's forever loop is 10.212 seconds when the interval method is called THEN:

currentTick:=      10212 ms
currentInterval:=  10200 ms

NowFunc_T

typedef ElapsedTime::Precision_T(* Cpl::System::PeriodicScheduler::NowFunc_T) ()

Defines the function that returns current system.

This method has two purposes: 1) It simplifies unit testing because it breaks the dependency on 'real time 2) Makes unit testing easier

ReportSlippageFunc_T

typedef void(* Cpl::System::PeriodicScheduler::ReportSlippageFunc_T) (Interval_T &intervalThatSlipped, ElapsedTime::Precision_T currentTick, ElapsedTime::Precision_T missedInterval)

Defines the method that is used to report to the Application when an Interval does not execute 'on time'.

Where: intervalThatSlipped - Reference to the interval that did not execute on time currentTick - The system time when the scheduler executed the interval missedInterval - The interval boundary that was missed intervalContext - Application defined argument/value that was passed to the interval method.

Constructor & Destructor Documentation

PeriodicScheduler()

Cpl::System::PeriodicScheduler::PeriodicScheduler	(	Interval_T	intervals[],
		Hook_T	beginThreadProcessing = nullptr,
		Hook_T	endThreadProcessing = nullptr,
		ReportSlippageFunc_T	slippageFunc = nullptr,
		NowFunc_T	nowFunc = ElapsedTime::precision
	)

Constructor.

The application provides a variable length array of interval definitions that will be scheduled. The last entry in the array must contain a 'null' Interval_T definition (i.e. all fields set to zero). The Scheduler assumes that each Interval_T definition has a unique period time.

The individual 'intervals' MUST be initialized (either statically or by calling initializeInterval()) before creating the scheduler.

Notes:

• When extending a event based (i.e. inherits from EventLoop) runnable object with scheduling, the Application should define all of the scheduled Intervals to have period times that are multiples of the EventLoop's 'timeOutPeriodInMsec' constructor value.

~PeriodicScheduler()

virtual Cpl::System::PeriodicScheduler::~PeriodicScheduler ( )

inlinevirtual

Virtual destructor.

Member Function Documentation

beginLoop()

virtual void Cpl::System::PeriodicScheduler::beginLoop ( )

virtual

This method is expected to be called ONCE when the 'thread' is started and prior to the thread entering its 'forever' loop.

endLoop()

virtual void Cpl::System::PeriodicScheduler::endLoop ( )

virtual

This method is expected to be called ONCE when the 'thread' has exited its 'forever' loop (but before the thread has actually terminated)

executeScheduler()

virtual bool Cpl::System::PeriodicScheduler::executeScheduler ( )

virtual

This method is used to invoke the scheduler.

When called zero or more Interval definitions will be executed. The method returns true if at least one Interval was executed.

If a scheduled Interval does not execute 'on time', then the reportSlippage() method will called. It is the Application's to decide (what if anything) is done when there is slippage in the scheduling. The slippage is reported AFTER the Interval's IntervalCallbackFunc_T is called.

setTimeMarker()

void Cpl::System::PeriodicScheduler::setTimeMarker ( Interval_T &  interval, ElapsedTime::Precision_T  currentTick  )

protectednoexcept

Helper method to Round DOWN to the nearest 'interval' boundary.

A side effect the rounding-down is the FIRST execution of an interval will NOT be accurate (i.e. will be something less than 'periodMs').

Member Data Documentation

m_beginThreadFunc

Hook_T Cpl::System::PeriodicScheduler::m_beginThreadFunc

protected

Application hook during thread start-up.

m_endThreadFunc

Hook_T Cpl::System::PeriodicScheduler::m_endThreadFunc

protected

Application hook during thread shutdown.

m_firstExecution

bool Cpl::System::PeriodicScheduler::m_firstExecution

protected

Flag to managing the 'first' execution.

m_intervals

Interval_T* Cpl::System::PeriodicScheduler::m_intervals

protected

List of Intervals Pointers.

m_nowFunc

NowFunc_T Cpl::System::PeriodicScheduler::m_nowFunc

protected

Current system callback.

m_reportSlippage

ReportSlippageFunc_T Cpl::System::PeriodicScheduler::m_reportSlippage

protected

Report slippage method.

---

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

• Cpl/System/PeriodicScheduler.h