Abstract class to assist in designing thread-based execution sequences. More...

#include <BaseThread.h>

Public Member Functions
	BaseThread (const char *threadName)
	Construct a new Base Thread object.

	BaseThread (const BaseThread &)=delete
	The Copy constructor is deleted to avoid copying instances.

BaseThread &	operator= (const BaseThread &)=delete
	The assignment operator constructor is deleted to avoid copying instances.

virtual	~BaseThread () noexcept
	The destructor de-initializes the singleton. It is not likely to be called in released products, but is implemented to support unit testing.

OS_Thread *	GetThreadId () noexcept
	Get the pointer to the thread.

bool	IsInitialized () const noexcept
	This function checks if the class is initialized;.

bool	EnsureInitialized () noexcept
	Initialize the thread.

bool	Suspend () noexcept
	Suspend the underlying thread OS task.

bool	Resume () noexcept
	Resume the underlying thread OS task.

bool	IsSuspended () noexcept
	Check the status of the underlying thread OS task.

bool	IsThreadCreated () noexcept

bool	IsThreadStopRequested () noexcept

bool	IsSetupComplete () const noexcept

bool	IsThreadRunning () const noexcept

bool	IsThreadStopped () const noexcept

bool	IsCleanupComplete () const noexcept

bool	IsThreadInStepDelay () const noexcept

bool	Start () noexcept
	Starts the thread.

virtual bool	StartAction () noexcept
	Start Action that can be run to see if Start() qualifies to start thread.

bool	Stop () noexcept
	Stops the thread.

virtual bool	Setup () noexcept=0
	Setup the thread.

virtual uint32_t	Step () noexcept=0
	Steps the thread through a single execution cycle .

virtual bool	Cleanup () noexcept=0
	Cleanup code that exists once the thread step sequence is stopped. The cleanup function should generally clear the setup flag to ensure the thread goes back through setup again.

const char *	GetThreadName () noexcept
	Returns the Base thread name.

bool	StartThreadAndWaitToVerify (uint32_t startTimeoutMsec=1000)
	[BLOCKING] Signals a BaseThread to start and waits to make sure it's started within the given timeout.

bool	StopThreadAndWaitToVerify (uint32_t stopTimeoutMsec)
	[BLOCKING] Signals a BaseThread to stop and waits to make sure it's started within the given timeout.

uint32_t	GetStackHighWaterMark () const noexcept
	Get the minimum remaining stack of the task.

bool	ChangePriority (uint32_t newPriority) noexcept
	Change the running priority of the thread.

Protected Member Functions
void	WaitForStart () noexcept
	Starts the thread.

virtual bool	Initialize () noexcept=0
	Function to initialize thread. Generally, the initialize function should return false rather than causing a low level fault.

virtual bool	ResetVariables () noexcept=0
	Resets all member variables to their initial states.

bool	CreateBaseThread (uint8_t *stack, OS_Ulong stackSizeBytes, OS_Uint priority, OS_Uint preempt_threshold, OS_Ulong timeSliceAllowed, OS_Uint auto_start) noexcept
	Function to Create TX thread.

bool	CreateBaseThread (uint8_t *stack, OS_Ulong stackSizeBytes, OS_Uint priority, OS_Uint preempt_threshold, OS_Ulong timeSliceAllowed, OS_Uint auto_start, int core_id) noexcept
	Pinned-to-core variant of CreateBaseThread (FreeRTOS / SMP).

void	MarkSetupComplete () noexcept
	Mark the setup as complete.

void	ClearSetupComplete () noexcept
	Clear the setup completion flag.

void	MarkCleanupComplete () noexcept
	Mark the cleanup as complete.

void	ClearCleanupComplete () noexcept
	Clear the cleanup flag.

void	MarkThreadRunning () noexcept
	Mark the thread as running.

void	ClearThreadRunning () noexcept
	Mark the thread as not running.

void	MarkThreadStopRequested () noexcept
	Indicate a request to stop the thread.

void	ClearThreadStopRequested () noexcept
	Clear the stop request for the thread.

void	MarkThreadStepInDelay () noexcept
	Indicate a request to stop the thread.

void	ClearThreadStepInDelay () noexcept
	Clear the stop request for the thread.

Static Protected Member Functions
static void	ThreadEntry (OS_Ulong instanceAddress)
	Thread entry that will be running.

Protected Attributes
bool	initialized

OS_Thread	osThread

const char *	osThreadName

bool	osThreadCreated

SignalSemaphore	signalSemaphore

Static Protected Attributes
static constexpr char	baseThreadStartSemaphoreBaseName [] = "BaseThreadStartSem-"

Private Attributes
uint32_t	waitBeforeStep

uint32_t	minTimestampBeforeNextStep

std::atomic< bool >	threadRunning

std::atomic< bool >	threadStepInDelay

std::atomic< bool >	setupComplete

std::atomic< bool >	cleanupComplete

std::atomic< bool >	stopThreadRequested

Detailed Description

Abstract class to assist in designing thread-based execution sequences.

Threads are intended to run indefinitely but can be started and stopped multiple times. On start, the Setup() function is executed followed by a continuous loop awaiting a stop signal, repeatedly calling the Step() function. On a stop signal, the Exit() function is executed for cleanup.

Constructor & Destructor Documentation

◆ BaseThread() [1/2]

BaseThread::BaseThread ( const char * threadName )

Construct a new Base Thread object.

BASE THREAD ITEMS BASE NAMES.

Parameters

threadName	Name of the thread.
threadSemaphore	Semaphore associated with the thread.

Base thread start semaphore base osThreadName that will be pre-fixed on the thread Name BASE THREAD

The constructor initializes the thread and prepares it to start

Returns: n/a

No code at this moment.

◆ BaseThread() [2/2]

BaseThread::BaseThread ( const BaseThread & )

delete

The Copy constructor is deleted to avoid copying instances.

Returns: n/a

◆ ~BaseThread()

BaseThread::~BaseThread ( )

virtualnoexcept

The destructor de-initializes the singleton. It is not likely to be called in released products, but is implemented to support unit testing.

The destructor de-initializes the thread. It is not likely to be called in released products, but will support unit testing.

Returns: n/a

Member Function Documentation

◆ ChangePriority()

bool BaseThread::ChangePriority ( uint32_t newPriority )

noexcept

Change the running priority of the thread.

◆ Cleanup()

virtual bool BaseThread::Cleanup ( )

pure virtualnoexcept

Cleanup code that exists once the thread step sequence is stopped. The cleanup function should generally clear the setup flag to ensure the thread goes back through setup again.

Returns: True if cleanup was actually ran, false otherwise which could indicate that mode is currently active.

◆ ClearCleanupComplete()

void BaseThread::ClearCleanupComplete ( )

inlineprotectednoexcept

Clear the cleanup flag.

◆ ClearSetupComplete()

void BaseThread::ClearSetupComplete ( )

inlineprotectednoexcept

Clear the setup completion flag.

◆ ClearThreadRunning()

void BaseThread::ClearThreadRunning ( )

inlineprotectednoexcept

Mark the thread as not running.

◆ ClearThreadStepInDelay()

void BaseThread::ClearThreadStepInDelay ( )

inlineprotectednoexcept

Clear the stop request for the thread.

◆ ClearThreadStopRequested()

void BaseThread::ClearThreadStopRequested ( )

inlineprotectednoexcept

Clear the stop request for the thread.

◆ CreateBaseThread() [1/2]

bool BaseThread::CreateBaseThread	(	uint8_t *	stack,
		OS_Ulong	stackSizeBytes,
		OS_Uint	priority,
		OS_Uint	preempt_threshold,
		OS_Ulong	timeSliceAllowed,
		OS_Uint	auto_start
	)

protectednoexcept

Function to Create TX thread.

Parameters

name	Name of thread
stack	- statically allocated stack
stackSizeBytes	Number of bytes allocated
priority	- thread priority
preempt_threshold	- thread preemption priority
timeSliceAllowed	- Time slice allowed to run before being preempted.
auto_start	- Automatic start selection.
osThreadName	Name of thread
stack	- statically allocted stack
stackSizeBytes	Numer of bytes allocated
priority	- thread priority
preempt_threshold	- thread preemption priority
timeSliceAllowed	-
auto_start	-

◆ CreateBaseThread() [2/2]

bool BaseThread::CreateBaseThread	(	uint8_t *	stack,
		OS_Ulong	stackSizeBytes,
		OS_Uint	priority,
		OS_Uint	preempt_threshold,
		OS_Ulong	timeSliceAllowed,
		OS_Uint	auto_start,
		int	core_id
	)

protectednoexcept

Pinned-to-core variant of CreateBaseThread (FreeRTOS / SMP).

Identical to CreateBaseThread but pins the new task to core_id. Pass core_id < 0 (e.g. -1) for "no affinity" — equivalent to the non-pinned variant. On single-core builds the affinity is ignored.

Parameters

core_id CPU core to pin the task to (0 or 1 on ESP32-S3).

Then, if the thread is not already created, create it

Create the OS Thread (pinned to core_id if >= 0, no affinity otherwise).

If successfully created

Mark the base thread as created.

◆ EnsureInitialized()

bool BaseThread::EnsureInitialized ( )

inlinenoexcept

Initialize the thread.

This function initializes and creates the thread, setting up all necessary parameters. It must be called before the thread can be started.

Returns: True if actions successful, false otherwise.

◆ GetStackHighWaterMark()

uint32_t BaseThread::GetStackHighWaterMark ( ) const

noexcept

Get the minimum remaining stack of the task.

◆ GetThreadId()

OS_Thread * BaseThread::GetThreadId ( )

inlinenoexcept

Get the pointer to the thread.

Returns: OS_Thread* Pointer to the thread.

◆ GetThreadName()

const char * BaseThread::GetThreadName ( )

noexcept

Returns the Base thread name.

Returns the Base thread osThreadName.

Returns: Returns the base thread name.; Returns the base thread osThreadName.

◆ Initialize()

virtual bool BaseThread::Initialize ( )

protectedpure virtualnoexcept

Function to initialize thread. Generally, the initialize function should return false rather than causing a low level fault.

Returns: true if able to initialize flash interface, false otherwise

◆ IsCleanupComplete()

bool BaseThread::IsCleanupComplete ( ) const

inlinenoexcept

◆ IsInitialized()

bool BaseThread::IsInitialized ( ) const

inlinenoexcept

This function checks if the class is initialized;.

Returns: true if calibrated, false otherwise

◆ IsSetupComplete()

bool BaseThread::IsSetupComplete ( ) const

inlinenoexcept

◆ IsSuspended()

bool BaseThread::IsSuspended ( )

noexcept

Check the status of the underlying thread OS task.

Returns: True if action successful, false otherwise.

◆ IsThreadCreated()

bool BaseThread::IsThreadCreated ( )

inlinenoexcept

◆ IsThreadInStepDelay()

bool BaseThread::IsThreadInStepDelay ( ) const

inlinenoexcept

◆ IsThreadRunning()

bool BaseThread::IsThreadRunning ( ) const

inlinenoexcept

◆ IsThreadStopped()

bool BaseThread::IsThreadStopped ( ) const

inlinenoexcept

◆ IsThreadStopRequested()

bool BaseThread::IsThreadStopRequested ( )

inlinenoexcept

◆ MarkCleanupComplete()

void BaseThread::MarkCleanupComplete ( )

inlineprotectednoexcept

Mark the cleanup as complete.

◆ MarkSetupComplete()

void BaseThread::MarkSetupComplete ( )

inlineprotectednoexcept

Mark the setup as complete.

◆ MarkThreadRunning()

void BaseThread::MarkThreadRunning ( )

inlineprotectednoexcept

Mark the thread as running.

◆ MarkThreadStepInDelay()

void BaseThread::MarkThreadStepInDelay ( )

inlineprotectednoexcept

Indicate a request to stop the thread.

◆ MarkThreadStopRequested()

void BaseThread::MarkThreadStopRequested ( )

inlineprotectednoexcept

Indicate a request to stop the thread.

◆ operator=()

BaseThread & BaseThread::operator= ( const BaseThread & )

delete

The assignment operator constructor is deleted to avoid copying instances.

Returns: n/a

◆ ResetVariables()

virtual bool BaseThread::ResetVariables ( )

protectedpure virtualnoexcept

Resets all member variables to their initial states.

This method is designed to reset all member variables to a known state, either to their initial values as set in the constructor, or to zero (or false, or other suitable default values). This can be useful in situations where the object needs to be reused or reinitialized.

Note: This method is marked noexcept, indicating that it does not throw exceptions.

◆ Resume()

bool BaseThread::Resume ( )

noexcept

Resume the underlying thread OS task.

Returns: True if action successful, false otherwise.

◆ Setup()

virtual bool BaseThread::Setup ( )

pure virtualnoexcept

Setup the thread.

This function setups up for execution of the thread whenever it is started or re-started. For example, this allows the valve manifold to be configured prior to starting thread thread. It can also be called prior to Start() e.g in response to settings Confirm.

Returns: True if setup was actually ran, false otherwise which could indicate that mode is current active.

◆ Start()

bool BaseThread::Start ( )

noexcept

Starts the thread.

This function starts the execution of the thread if not already running. This results in executing Setup() if it has not already been done. The base class implementation simply signals the associated semaphore.

The starting called may be ignored depending on case therefore a bool will be returned.

Returns: True if the thread was signaled to start, false otherwise.

Note: The thread must be waiting on a start call for this to take any effect.

Run start action

If successful, signal the thread via the designated semaphore to start the process

Otherwise, indicate that we cannot start thread.

◆ StartAction()

bool BaseThread::StartAction ( )

virtualnoexcept

Start Action that can be run to see if Start() qualifies to start thread.

Returns: True if start actions are successful and Start() can proceed to signal thread to start.; False otherwise.

◆ StartThreadAndWaitToVerify()

bool BaseThread::StartThreadAndWaitToVerify ( uint32_t startTimeoutMsec = 1000 )

[BLOCKING] Signals a BaseThread to start and waits to make sure it's started within the given timeout.

Parameters

threadToStart	BaseThread to start
startTimeoutMsec	Timeout to make sure Thread has started in Milliseconds.

Returns: True if thread is started, false otherwise

Start the thread

Function that will test if the thread has been started

Expecting true within the timeout specified

Return result

Return false indicating Start() call failure

◆ Step()

virtual uint32_t BaseThread::Step ( )

pure virtualnoexcept

Steps the thread through a single execution cycle .

This function steps the execution of the service thread if not already running. Then it returns how much it needs to wait before next Step() is called.

Returns: The time in milliseconds to wait before running calling next Step()

◆ Stop()

bool BaseThread::Stop ( )

noexcept

Stops the thread.

This function stops the execution of the thread. The thread can be resumed later by calling service_start(). The base class simple sets the variable indicating the thread should stop.

Returns: True if the thread was signaled to stop, false otherwise.

In case we are somehow suspended in our step, let's resume.

◆ StopThreadAndWaitToVerify()

bool BaseThread::StopThreadAndWaitToVerify ( uint32_t stopTimeoutMsec )

[BLOCKING] Signals a BaseThread to stop and waits to make sure it's started within the given timeout.

Parameters

threadToStop	BaseThread to stop
stopTimeoutMsec	Timeout to make sure Thread has stopped in Milliseconds.

Returns: True if thread is stopped, false otherwise

Stop the thread

Function that will test if the thread has been stopped

Expecting true within the timeout specified

Return result

Return false indicating Stop() call failure

◆ Suspend()

bool BaseThread::Suspend ( )

noexcept

Suspend the underlying thread OS task.

Returns: True if action successful, false otherwise.

◆ ThreadEntry()

void BaseThread::ThreadEntry ( OS_Ulong instanceAddress )

staticprotected

Thread entry that will be running.

Parameters

instanceAddress

Clear the thread running flag so that we can Start() properly.

Wait for a signal to start ( it occurs in BaseThread Start() )

Reset all necessary variables

< Thread should be marked as running immediately.

< Clear this flag in case CALLER didn't wait to send START command until the mode was completely stopped and then sent another STOP flag because CALLER doesn't see the mode starting, this should not be the case in the final product but necessary during development.

< Clear the cleanup complete flag.

Main control loop sequence

Calculate next timestamp to Step() again

Mark that we are going to a delay

Delay requested time

Clear that we are in a delay

Make sure to mark

Clean up before exiting the thread.

Let's set that the cleanup flag so that we can make that a cleanup is complete

Let's clear the setup complete flag so that a setup is ran before re-entering loop.

◆ WaitForStart()

void BaseThread::WaitForStart ( )

protectednoexcept

Starts the thread.

Puts the caller thread in a waiting state until the service_start() is called.

This function waits for the thread to be signalled to start.

Note: The service thread must be waiting on a start call for this to take any effect.

Member Data Documentation

◆ baseThreadStartSemaphoreBaseName

constexpr char BaseThread::baseThreadStartSemaphoreBaseName[] = "BaseThreadStartSem-"

staticconstexprprotected

◆ cleanupComplete

std::atomic<bool> BaseThread::cleanupComplete

private

◆ initialized

bool BaseThread::initialized

protected

◆ minTimestampBeforeNextStep

uint32_t BaseThread::minTimestampBeforeNextStep

private

◆ osThread

OS_Thread BaseThread::osThread

protected

◆ osThreadCreated

bool BaseThread::osThreadCreated

protected

◆ osThreadName

const char* BaseThread::osThreadName

protected

◆ setupComplete

std::atomic<bool> BaseThread::setupComplete

private

◆ signalSemaphore

SignalSemaphore BaseThread::signalSemaphore

protected

◆ stopThreadRequested

std::atomic<bool> BaseThread::stopThreadRequested

private

◆ threadRunning

std::atomic<bool> BaseThread::threadRunning

private

◆ threadStepInDelay

std::atomic<bool> BaseThread::threadStepInDelay

private

◆ waitBeforeStep

uint32_t BaseThread::waitBeforeStep

private

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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BaseThread() [1/2]

◆ BaseThread() [2/2]

◆ ~BaseThread()

Member Function Documentation

◆ ChangePriority()

◆ Cleanup()

◆ ClearCleanupComplete()

◆ ClearSetupComplete()

◆ ClearThreadRunning()

◆ ClearThreadStepInDelay()

◆ ClearThreadStopRequested()

◆ CreateBaseThread() [1/2]

◆ CreateBaseThread() [2/2]

◆ EnsureInitialized()

◆ GetStackHighWaterMark()

◆ GetThreadId()

◆ GetThreadName()

◆ Initialize()

◆ IsCleanupComplete()

◆ IsInitialized()

◆ IsSetupComplete()

◆ IsSuspended()

◆ IsThreadCreated()

◆ IsThreadInStepDelay()

◆ IsThreadRunning()

◆ IsThreadStopped()

◆ IsThreadStopRequested()

◆ MarkCleanupComplete()

◆ MarkSetupComplete()

◆ MarkThreadRunning()

◆ MarkThreadStepInDelay()

◆ MarkThreadStopRequested()

◆ operator=()

◆ ResetVariables()

◆ Resume()

◆ Setup()

◆ Start()

◆ StartAction()

◆ StartThreadAndWaitToVerify()

◆ Step()

◆ Stop()

◆ StopThreadAndWaitToVerify()

◆ Suspend()

◆ ThreadEntry()

◆ WaitForStart()

Member Data Documentation

◆ baseThreadStartSemaphoreBaseName

◆ cleanupComplete

◆ initialized

◆ minTimestampBeforeNextStep

◆ osThread

◆ osThreadCreated

◆ osThreadName

◆ setupComplete

◆ signalSemaphore

◆ stopThreadRequested

◆ threadRunning

◆ threadStepInDelay

◆ waitBeforeStep