This abstract class defines the operations that can be performed on a thread. More...

Detailed Description

This abstract class defines the operations that can be performed on a thread.

NOTE: The thread contains a built in counting semaphore that is usable by the developer. This semaphore can be used to assist in implementing inter-thread-communications and/or ISR-to-thread communications.

#include <Thread.h>

Inheritance diagram for Cpl::System::Thread:

[legend]

Collaboration diagram for Cpl::System::Thread:

[legend]

Classes
class	Traverser
	This abstract class defines the client interface for walking the list of threads, i.e. More...

Public Member Functions
virtual	~Thread ()
	Virtual destructor.

virtual const char *	getName () noexcept=0
	This method returns the name (null terminated string) of the current thread.

virtual size_t	getId () noexcept=0
	This method returns the task's unique identifier.

virtual bool	isRunning (void) noexcept=0
	This method returns the 'running' state of the thread.

virtual Cpl_System_Thread_NativeHdl_T	getNativeHandle (void) noexcept=0
	Returns the native thread handle.

virtual Runnable &	getRunnable (void) noexcept=0
	This method returns a reference to the thread's Runnable object.

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

virtual int	signal (void) noexcept=0
	This method is called by client to cause the server to become unblock and ready to run.

virtual int	su_signal (void) noexcept=0
	Same as signal(), EXCEPT this method can ONLY be called from supervisor mode and/or ISR contexts.

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.

Static Public Member Functions
static Thread &	getCurrent () noexcept
	This method returns a reference to the currently executing thread.

static Thread *	tryGetCurrent () noexcept
	Special version of getCurrent().

static void	wait () noexcept
	This method causes the CURRENT thread to wait until its 'thread semaphore' is signal/set.

static bool	tryWait () noexcept
	This method is similar to Semaphore::tryWait(), except that it operates on the thread semaphore.

static bool	timedWait (unsigned long timeoutInMsec) noexcept
	Same as wait(), except the call will return after 'timeoutInMsec' has expired without the thread being signaled.

static const char *	myName () noexcept
	Returns the name for the current thread (i.e.

static size_t	myId () noexcept
	Returns the ID for the current thread (i.e.

static Runnable &	myRunnable () noexcept
	This method returns a reference to the current thread' runnable instance.

static void	traverse (Thread::Traverser &client) noexcept
	Internal Iterator that allows the Client to traverse the list active threads.

static Thread *	create (Runnable &runnable, const char name, int priority=CPL_SYSTEM_THREAD_PRIORITY_NORMAL, int stackSize=0, void stackPtr=0, bool allowSimTicks=true)
	This method creates a thread according to the specified parameters.

static void	destroy (Thread &threadToDestroy)
	This method is used to destroy a thread that was created by the Thread Factory.

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.

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

void *	m_inListPtr_
	Debug field.

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.

Constructor & Destructor Documentation

◆ ~Thread()

virtual Cpl::System::Thread::~Thread ( )

inlinevirtual

Virtual destructor.

Reimplemented in Cpl::System::BareMetal::Thread, Cpl::System::Cpp11::Thread, Cpl::System::FreeRTOS::Thread, Cpl::System::Posix::Thread, and Cpl::System::Win32::Thread.

Member Function Documentation

◆ create()

static Thread * Cpl::System::Thread::create	(	Runnable &	runnable,
		const char *	name,
		int	priority = `CPL_SYSTEM_THREAD_PRIORITY_NORMAL`,
		int	stackSize = `0`,
		void *	stackPtr = `0`,
		bool	allowSimTicks = `true`
	)

static

This method creates a thread according to the specified parameters.

The thread/task begins execution immediately upon its creation.

NOTE: Not all platform support all options, e.g. The C++11 multi threading support does not directly support thread priorities.

Returns: A pointer to the Thread created, OR 0 if the was an error.

Parameters

runnable	a runnable object which is started when the task is created
name	a null terminated string that represent that thread's name
priority	a priority ranging from highest priority (CPL_SYSTEM_THREAD_PRIORITY_HIGHEST) to lowest priority (CPL_SYSTEM_THREAD_PRIORITY_LOWEST). Priorities are defined in relative 'levels' to the max/normal/min settings because there is no standardized priority settings across Operating Systems. If the priority value exceeds the upper/lower bounds the platform's priority range, the thread's priority will be clamped to the upper/lower bound of the priority range.
stackSize	Requested size, in bytes, of the stack for the thread. A value of of zero will size the thread's stack per the platform's default stack size setting.
stackPtr	Pointer to the stack memory to be used for the thread's stack. If zero is passed, then the underlying platform/OS will allocate the stack memory.
allowSimTicks	With this argument is true the thread will be created to use/support simulated time when 'Simulate ticks' are enabled. A value false will force the thread to always be a 'real time' thread. See Cpl::System::SimTicks for more details about simulated time.

◆ destroy()

static void Cpl::System::Thread::destroy ( Thread & threadToDestroy )

static

This method is used to destroy a thread that was created by the Thread Factory.

If you are going to delete a thread that was created by the Thread Factory, you MUST use the Factory's destroy method to delete it to properly insure that the memory used to create the task is released correctly.

NOTES:

o The application should only delete/destroy a thread AFTER the
  thread's Runnable object.run() method has ended/terminated.  If
  the thread is destroy/delete before run() has completed, there is
  NO GUARANTEE with respect to whether or not the thread has
  released all acquired resources!
o NOT ALL Platforms support brute-force termination of threads,
  e.g. in C++11 there is no method/interface to forcibly terminate
  a thread.  Once again -->it is a HIGHLY DISCOURAGED to design
  your application where you need to forcibly terminate threads.
o This method only deletes/destroys the Thread instance -- it does
  NOT delete/destroy the associated Runnable instance.

◆ getCurrent()

static Thread & Cpl::System::Thread::getCurrent ( )

staticnoexcept

This method returns a reference to the currently executing thread.

◆ getId()

virtual size_t Cpl::System::Thread::getId ( )

pure virtualnoexcept

This method returns the task's unique identifier.

Implemented in Cpl::System::BareMetal::Thread, Cpl::System::Cpp11::Thread, Cpl::System::FreeRTOS::Thread, Cpl::System::Posix::Thread, and Cpl::System::Win32::Thread.

◆ getName()

virtual const char * Cpl::System::Thread::getName ( )

pure virtualnoexcept

This method returns the name (null terminated string) of the current thread.

Implemented in Cpl::System::BareMetal::Thread, Cpl::System::Cpp11::Thread, Cpl::System::FreeRTOS::Thread, Cpl::System::Posix::Thread, and Cpl::System::Win32::Thread.

◆ getNativeHandle()

virtual Cpl_System_Thread_NativeHdl_T Cpl::System::Thread::getNativeHandle ( void )

pure virtualnoexcept

Returns the native thread handle.

Note: This handle can NOT be used a handle/reference/pointer to a Thread object instance.

Implemented in Cpl::System::BareMetal::Thread, Cpl::System::Cpp11::Thread, Cpl::System::FreeRTOS::Thread, Cpl::System::Posix::Thread, and Cpl::System::Win32::Thread.

◆ getRunnable()

virtual Runnable & Cpl::System::Thread::getRunnable ( void )

pure virtualnoexcept

This method returns a reference to the thread's Runnable object.

Implemented in Cpl::System::BareMetal::Thread, Cpl::System::Cpp11::Thread, Cpl::System::FreeRTOS::Thread, Cpl::System::Posix::Thread, and Cpl::System::Win32::Thread.

◆ isRunning()

virtual bool Cpl::System::Thread::isRunning ( void )

pure virtualnoexcept

This method returns the 'running' state of the thread.

If the method returns false, the underlying thread has terminated (i.e. the run() method has completed) and then the Thread object/instance can be safely deleted using the destroy() method below.

Implemented in Cpl::System::BareMetal::Thread, Cpl::System::Cpp11::Thread, Cpl::System::FreeRTOS::Thread, Cpl::System::Posix::Thread, and Cpl::System::Win32::Thread.

◆ myId()

static size_t Cpl::System::Thread::myId ( )

staticnoexcept

Returns the ID for the current thread (i.e.

short-hand for threadPtr->getCurrent().getId()

◆ myName()

static const char * Cpl::System::Thread::myName ( )

staticnoexcept

Returns the name for the current thread (i.e.

short-hand for threadPtr->getCurrent().getName()

◆ myRunnable()

static Runnable & Cpl::System::Thread::myRunnable ( )

inlinestaticnoexcept

This method returns a reference to the current thread' runnable instance.

◆ timedWait()

static bool Cpl::System::Thread::timedWait ( unsigned long timeoutInMsec )

staticnoexcept

Same as wait(), except the call will return after 'timeoutInMsec' has expired without the thread being signaled.

The method return true if the Thread was signaled; else false is returned if the timeout period expired.

◆ traverse()

static void Cpl::System::Thread::traverse ( Thread::Traverser & client )

staticnoexcept

Internal Iterator that allows the Client to traverse the list active threads.

NOTES: o There is difference between an "active" thread and a Thread object instance. The underlying platform/OS determines if the a thread is "active", i.e. the thread is created and running. The Thread object gets created BEFORE the thread is active and exists AFTER thread terminates/end. Why the explanation, this method only includes "active" threads. Threads that have terminated, but that their associated Thread object instance has not been delete/destroyed will NOT show up in the active list. o This call is mutex protected. It will prevent new threads from being created/deleted until it has completed.

◆ tryGetCurrent()

static Thread * Cpl::System::Thread::tryGetCurrent ( )

staticnoexcept

Special version of getCurrent().

getCurrent() will trigger a FATAL error when called from a NON CPL thread. tryGetCurrent() will return a nullptr when it detects that the current thread is NOT a CPL thread.

This method should ONLY be used when your application has mix of CPL and non-CPL threads, i.e. the default should be to use getCurrent().

◆ tryWait()

static bool Cpl::System::Thread::tryWait ( )

staticnoexcept

This method is similar to Semaphore::tryWait(), except that it operates on the thread semaphore.

◆ wait()

static void Cpl::System::Thread::wait ( )

staticnoexcept

This method causes the CURRENT thread to wait until its 'thread semaphore' is signal/set.

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

Cpl/System/Thread.h

Detailed Description

Classes

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ ~Thread()

Member Function Documentation

◆ create()

◆ destroy()

◆ getCurrent()

◆ getId()

◆ getName()

◆ getNativeHandle()

◆ getRunnable()

◆ isRunning()

◆ myId()

◆ myName()

◆ myRunnable()

◆ timedWait()

◆ traverse()

◆ tryGetCurrent()

◆ tryWait()

◆ wait()