This concrete class is a Runnable object that provides a event driven execution model for a thread. More...

Detailed Description

This concrete class is a Runnable object that provides a event driven execution model for a thread.

The thread will remaining blocked until an "event" occurs. The following "events" are supported:

1) The EventLoop Semaphore was signaled 2) A Event Flag was set( Cpl::System::EventFlag) 3) A Software Timer expiring (Cpl::System::Timer)

To receive a callbacks when Event Flags are set, the application must create a child class and provide its own implementation of the processEventFlag() method.

The class also provides a mechanism for registering 'other' events to be processed.

Note: The EventLoop does NOT use/consume the Thread Semaphore.

#include <EventLoop.h>

Inheritance diagram for Cpl::System::EventLoop:

[legend]

Collaboration diagram for Cpl::System::EventLoop:

[legend]

Public Member Functions
	EventLoop (unsigned long timeOutPeriodInMsec=OPTION_CPL_SYSTEM_EVENT_LOOP_TIMEOUT_PERIOD, SharedEventHandlerApi *eventHandler=0)
	Constructor.

virtual	~EventLoop ()
	Virtual destructor.

int	signal (void) noexcept
	See Cpl::System::Signable.

int	su_signal (void) noexcept
	See Cpl::System::Signable.

void	pleaseStop ()
	See Cpl::System::Runnable.

void	notifyEvents (Cpl_System_EventFlag_T events) noexcept
	See Cpl::System::EventFlag.

void	notify (uint8_t eventNumber) noexcept
	See Cpl::System::EventFlag.

void	su_notifyEvents (Cpl_System_EventFlag_T events) noexcept
	See Cpl::System::EventFlag.

void	su_notify (uint8_t eventNumber) noexcept
	See Cpl::System::EventFlag.

void	setThreadOfExecution_ (Thread *myThreadPtr)
	See Cpl::System::Runnable.

Public Member Functions inherited from Cpl::System::Runnable
virtual	~Runnable ()
	Virtual destructor.

virtual void	run ()
	This method is called when the Thread is started.

virtual bool	isRunning () noexcept
	This method returns true if the instance has 'entered' its run method; false is returned, i.e.

Public Member Functions inherited from Cpl::System::EventFlag
virtual	~EventFlag ()
	Virtual destructor.

Public Member Functions inherited from Cpl::System::Signable
virtual	~Signable ()
	Virtual destructor.

Public Member Functions inherited from Cpl::Container::Item
bool	insert_ (void *newContainerPtr)
	Helper method to trap when inserting an item in multiple containers.

bool	isInContainer_ (const void *containerPtr) const noexcept
	Returns 'true' if the instance is in the specified container.

Public Member Functions inherited from Cpl::System::TimerManager
	TimerManager ()
	Constructor.

void	startManager (void) noexcept
	This method starts the Timer Manager.

void	processTimers (void) noexcept
	This method processes the current active timer lists.

bool	areActiveTimers (void) noexcept
	Returns true if there are NO active timers.

void	attach (CounterCallback_ &clientToCallback) noexcept
	See Cpl::System::CounterCallback_.

bool	detach (CounterCallback_ &clientToCallback) noexcept
	See Cpl::System::CounterCallback_.

unsigned long	msecToCounts (unsigned long milliseconds) noexcept
	See Cpl::System::CounterCallback_.

Public Member Functions inherited from Cpl::System::CounterSource_
virtual	~CounterSource_ ()
	Virtual Destructor.

Protected Member Functions
virtual void	startEventLoop () noexcept
	This method is used to initialize the Event Loop's thread has started to executed.

virtual bool	waitAndProcessEvents (bool skipWait=false) noexcept
	This method is used to wait (and process) the next event(s).

virtual void	stopEventLoop () noexcept
	This method is used to clean-up the Event Loop's when the thread is being stopped.

virtual void	processEventFlag (uint8_t eventNumber) noexcept
	This method is used (by the concrete child class(es)) to process one or more Event Flags.

void	appRun ()
	See Cpl::System::Runnable.

Protected Member Functions inherited from Cpl::System::Runnable
	Runnable ()
	Constructor.

Protected Member Functions inherited from Cpl::Container::Item
	Item ()
	Constructor.

	Item (const char *)
	Constructor used ONLY with the child class MapItem: -->special constructor to allow a Map to be statically allocated.

Protected Member Functions inherited from Cpl::System::TimerManager
void	addToActiveList (CounterCallback_ &clientToCallback) noexcept
	Helper method.

virtual void	tick (unsigned long milliseconds=1) noexcept
	This method is intended to be call by a the timing source and each call to this method represents that one tick has expired, i.e.

virtual void	tickComplete (void) noexcept
	This method is used by the Tick source to information the Timer Manager that there are no more ticks for the timing source's current tick cycle.

Protected Attributes
Thread *	m_myThreadPtr
	A pointer to the thread the Event Loop executes in.

SharedEventHandlerApi *	m_eventHandler
	My shared event handler (if I have one)

Cpl::System::Semaphore	m_sema
	Semaphore associated with the mailbox (note: the Thread semaphore is NOT used)

unsigned long	m_timeout
	Timeout period for waiting on the next event.

unsigned long	m_timeStartOfLoop
	Timestamp, in milliseconds, of start of event/wait loop.

Cpl_System_EventFlag_T	m_events
	The variable holds the current state of all Event Flags.

bool	m_run
	Flag used to help with the pleaseStop() request.

Protected Attributes inherited from Cpl::System::Runnable
bool	m_running
	Tracks the run state of the instance.

Protected Attributes inherited from Cpl::System::TimerManager
Cpl::Container::DList< CounterCallback_ >	m_counters
	List of active counters.

Cpl::Container::DList< CounterCallback_ >	m_pendingAttach
	List of Pending-to-attach counters (this happens when timers attach from the timer-expired-callbacks)

unsigned long	m_timeMark
	Elapsed time of the previous processing cycle.

unsigned long	m_timeNow
	Elapsed time of the current processing cycle.

bool	m_inTickCall
	Flag to tracks when I am actively processing/consuming ticks.

Additional Inherited Members
Static Public Member Functions inherited from Cpl::Container::Item
static void	remove_ (Item *itemPtr) noexcept
	Helper method to do the proper 'clean-up' for the multiple-containers-error-trap when removing an item from a container.

Public Attributes inherited from Cpl::Container::Item
void *	m_nextPtr_
	The link field.

void *	m_inListPtr_
	Debug field.

Constructor & Destructor Documentation

◆ EventLoop()

Cpl::System::EventLoop::EventLoop	(	unsigned long	timeOutPeriodInMsec = `OPTION_CPL_SYSTEM_EVENT_LOOP_TIMEOUT_PERIOD`,
		SharedEventHandlerApi *	eventHandler = `0`
	)

Constructor.

The 'timeOutPeriodInMsec' parameter specifies how long the EventLoop will wait for an event before timing out and processing the software timers. The value of 'timeOutPeriodInMsec' is the resolution of the timing source for the Software Timers, i.e. the event loop will 'wake-up' at least every 'timeOutPeriodInMsec' milliseconds.

A fatal error is generated if 'timeOutPeriodInMsec' is set to zero.

◆ ~EventLoop()

virtual Cpl::System::EventLoop::~EventLoop ( )

inlinevirtual

Virtual destructor.

Member Function Documentation

◆ appRun()

void Cpl::System::EventLoop::appRun ( )

protectedvirtual

See Cpl::System::Runnable.

Implements Cpl::System::Runnable.

Reimplemented in Cpl::Dm::MailboxServer, Cpl::Dm::PeriodicScheduler, Cpl::Itc::MailboxServer, and Cpl::Itc::PeriodicScheduler.

◆ notify()

void Cpl::System::EventLoop::notify ( uint8_t eventNumber )

virtualnoexcept

See Cpl::System::EventFlag.

Implements Cpl::System::EventFlag.

◆ notifyEvents()

void Cpl::System::EventLoop::notifyEvents ( Cpl_System_EventFlag_T events )

virtualnoexcept

See Cpl::System::EventFlag.

Implements Cpl::System::EventFlag.

◆ pleaseStop()

void Cpl::System::EventLoop::pleaseStop ( )

virtual

See Cpl::System::Runnable.

Reimplemented from Cpl::System::Runnable.

◆ processEventFlag()

virtual void Cpl::System::EventLoop::processEventFlag ( uint8_t eventNumber )

protectedvirtualnoexcept

This method is used (by the concrete child class(es)) to process one or more Event Flags.

This method is called when at least one Event Flag was set. The method is called N consecutive times - one call for each Event Flag that is set. The 'eventNumber' (which is zero based) identifies which Event Flag is/was set.

If no ShareEventHandler was provided when the event loop was created, the default implementation of this method does NOTHING; else the ShareEventHandler instance is used to process the event flag/number.

◆ setThreadOfExecution_()

void Cpl::System::EventLoop::setThreadOfExecution_ ( Thread * myThreadPtr )

virtual

See Cpl::System::Runnable.

Reimplemented from Cpl::System::Runnable.

◆ signal()

int Cpl::System::EventLoop::signal ( void )

virtualnoexcept

See Cpl::System::Signable.

Implements Cpl::System::Signable.

◆ startEventLoop()

virtual void Cpl::System::EventLoop::startEventLoop ( )

protectedvirtualnoexcept

This method is used to initialize the Event Loop's thread has started to executed.

This method is intended to be used by child classes that are extending the Event Loop. For this use case - this method MUST be called once on the beginning of the appRun() method and BEFORE the "main loop" for the appRun() method is entered.

◆ stopEventLoop()

virtual void Cpl::System::EventLoop::stopEventLoop ( )

protectedvirtualnoexcept

This method is used to clean-up the Event Loop's when the thread is being stopped.

This method is intended to be used by child classes that are extending the Event Loop. For this use case - this method MUST be called once AFTER the event-processing loop has exited.

◆ su_notify()

void Cpl::System::EventLoop::su_notify ( uint8_t eventNumber )

virtualnoexcept

See Cpl::System::EventFlag.

Implements Cpl::System::EventFlag.

◆ su_notifyEvents()

void Cpl::System::EventLoop::su_notifyEvents ( Cpl_System_EventFlag_T events )

virtualnoexcept

See Cpl::System::EventFlag.

Implements Cpl::System::EventFlag.

◆ su_signal()

int Cpl::System::EventLoop::su_signal ( void )

virtualnoexcept

See Cpl::System::Signable.

Implements Cpl::System::Signable.

◆ waitAndProcessEvents()

virtual bool Cpl::System::EventLoop::waitAndProcessEvents ( bool skipWait = false )

protectedvirtualnoexcept

This method is used to wait (and process) the next event(s).

This method returns after being woken up and processing all timer expired and pending Event Flag events. This method should always be wrapped in a loop (typically a forever loop).

If the 'skipWait' argument is set to true then the method does not wait for event - it simply processing the current event flags and timers. The use scenario for skipping the wait is for child classes to execute the event loop multiple times to drain their message/notifications queues one message/notification at a time (i.e. give equal time/priority to all types of events)

The method typically returns true. The method only returns false if the pleaseStop() method was called on the Event Loop instance.

This method is intended to be used by child classes that are extending the Event Loop. For this use case - this method MUST be called inside the child class's "main loop" in its the appRun() method.

Example appRun() for a child class extending the Event Loop:

void ChildEventLoop::appRun( void )
{
    startEventLoop();
    <child specific intialization>
 
    bool run = true;
    while( run )
    {
        run = waitAndProcessEvents();
        if ( run )
        {
            <child specific event processing>
        }
    }
    stopEventLoop()
}

Member Data Documentation

◆ m_eventHandler

SharedEventHandlerApi* Cpl::System::EventLoop::m_eventHandler

protected

My shared event handler (if I have one)

◆ m_events

Cpl_System_EventFlag_T Cpl::System::EventLoop::m_events

protected

The variable holds the current state of all Event Flags.

◆ m_myThreadPtr

Thread* Cpl::System::EventLoop::m_myThreadPtr

protected

A pointer to the thread the Event Loop executes in.

◆ m_run

bool Cpl::System::EventLoop::m_run

protected

Flag used to help with the pleaseStop() request.

◆ m_sema

Cpl::System::Semaphore Cpl::System::EventLoop::m_sema

protected

Semaphore associated with the mailbox (note: the Thread semaphore is NOT used)

◆ m_timeout

unsigned long Cpl::System::EventLoop::m_timeout

protected

Timeout period for waiting on the next event.

◆ m_timeStartOfLoop

unsigned long Cpl::System::EventLoop::m_timeStartOfLoop

protected

Timestamp, in milliseconds, of start of event/wait loop.

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

Cpl/System/EventLoop.h

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ EventLoop()

◆ ~EventLoop()

Member Function Documentation

◆ appRun()

◆ notify()

◆ notifyEvents()

◆ pleaseStop()

◆ processEventFlag()

◆ setThreadOfExecution_()

◆ signal()

◆ startEventLoop()

◆ stopEventLoop()

◆ su_notify()

◆ su_notifyEvents()

◆ su_signal()

◆ waitAndProcessEvents()

Member Data Documentation

◆ m_eventHandler

◆ m_events

◆ m_myThreadPtr

◆ m_run

◆ m_sema

◆ m_timeout

◆ m_timeStartOfLoop