#include <ar_classes.h>

Inheritance diagram for Ar::Thread:

Description

Preemptive thread class.

This thread class implements a preemptive thread with variable priority.

Threads may be allocated either globally or with the new operator. You can also allocate a thread locally, but you must be careful to keep the stack valid as long as the thread is running. There are two options for initialization. Either use one of the non-default constructors, or use the default constructor and call an init() method at some later point. Both the constructors and init methods take the same arguments. They accept a name, entry point, stack, and priority.

The entry point can be a global or static function that matches the ar_thread_entry_t prototype. Alternatively, there are constructor and init() variants that let you use a member function of a specific object as the entry point.

The init() method leaves the new thread suspended. To make the new thread eligible to run you must call the resume() method on it.

Collaboration diagram for Ar::Thread:

Public Member Functions
	Thread ()
	Default constructor.

	Thread (const char name, ar_thread_entry_t entry, void param, void *stack, unsigned stackSize, uint8_t priority, bool startImmediately=true)
	Constructor. More...

template<class T >
	Thread (const char name, T object, void(T::entry)(), void stack, unsigned stackSize, uint8_t priority, bool startImmediately=true)
	Constructor to set the thread entry to a member function. More...

	Thread (const char name, ar_thread_entry_t entry, void param, unsigned stackSize, uint8_t priority, bool startImmediately=true)
	Constructor to dynamically allocate the stack. More...

template<class T >
	Thread (const char name, T object, void(T::*entry)(), unsigned stackSize, uint8_t priority, bool startImmediately=true)
	Constructor to set the thread entry to a member function, using a dynamic stack. More...

virtual	~Thread ()
	Destructor.

const char *	getName () const
	Get the thread's name.

Thread init and cleanup
ar_status_t	init (const char name, ar_thread_entry_t entry, void param, void *stack, unsigned stackSize, uint8_t priority, bool startImmediately=true)
	Base initialiser. More...

template<class T >
ar_status_t	init (const char name, T object, void(T::entry)(), void stack, unsigned stackSize, uint8_t priority, bool startImmediately=true)
	Initializer to set the thread entry to a member function. More...

Thread priority
Accessors for the thread's priority.
uint8_t	getPriority () const
	Return the thread's current priority.

ar_status_t	setPriority (uint8_t priority)
	Change the thread's priority. More...

Info
uint32_t	getLoad ()
	Get the thread's system load.

uint32_t	getStackUsed ()
	Get the thread's maximum stack usage.

Public Member Functions inherited from ar_thread_t
void	block (ar_list_t &blockedList, uint32_t timeout)

void	unblockWithStatus (ar_list_t &blockedList, ar_status_t unblockStatus)

Static Public Member Functions
Accessors
Static members to get system-wide information.
static Thread *	getCurrent ()
	Returns the currently running thread object.

Protected Member Functions
ar_status_t	initForMemberFunction (const char name, void object, ar_thread_entry_t entry, void memberPointer, uint32_t memberPointerSize, void stack, unsigned stackSize, uint8_t priority, bool startImmediately)
	Special init method to deal with member functions.

virtual void	threadEntry (void *param)
	Virtual thread entry point. More...

Static Protected Member Functions
template<class T >
static void	member_thread_entry (void *param)
	Template function to invoke a thread entry point that is a member function.

static void	thread_entry (void *param)
	Static thread entry callback to invoke the virtual method.

Protected Attributes
uint8_t *	m_allocatedStack
	Dynamically allocated stack.

ar_thread_entry_t	m_userEntry
	User-specified thread entry point function.

Thread state
Control of and access to the thread state.
void	suspend ()
	Put thread in suspended state. More...

void	resume ()
	Make the thread eligible for execution. More...

ar_thread_state_t	getState () const
	Return the current state of the thread.

static void	sleep (unsigned milliseconds)
	Put the current thread to sleep for a certain amount of time. More...

static void	sleepUntil (unsigned wakeup)
	Put the current thread to sleep until a specific time. More...

Additional Inherited Members
Public Attributes inherited from ar_thread_t
ar_list_node_t	m_blockedNode
	Blocked list node.

void *	m_channelData
	Receive or send data pointer for blocked channel.

ar_thread_entry_t	m_entry
	Function pointer for the thread's entry point.

const char *	m_name
	Thread name.

ar_thread_port_data_t	m_portData
	Port-specific thread data.

uint8_t	m_priority
	Thread priority. 0 is the lowest priority.

ar_runloop_t *	m_runLoop
	Run loop associated with this thread.

uint32_t *	m_stackBottom
	Beginning of stack.

volatile uint8_t *	m_stackPointer
	Current stack pointer.

uint32_t *	m_stackTop
	Saved stack top address for computing stack usage.

ar_thread_state_t	m_state
	Current thread state.

ar_list_node_t	m_threadNode
	Main thread list node.

ar_status_t	m_unblockStatus
	Status code to return from a blocking function upon unblocking.

uint32_t	m_uniqueId
	Unique ID for this thread.

uint32_t	m_wakeupTime
	Tick count when a sleeping thread will awaken.

Constructor & Destructor Documentation

◆ Thread() [1/4]

Ar::Thread::Thread	(	const char *	name,
		ar_thread_entry_t	entry,
		void *	param,
		void *	stack,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately = `true`
	)

inline

Constructor.

Parameters

name	Name of the thread. If NULL, the thread's name is set to an empty string.
entry	Thread entry point taking one parameter and returning void.
param	Arbitrary pointer-sized value passed as the single parameter to the thread entry point.
stack	Pointer to the start of the thread's stack. This should be the stack's bottom, not it's top. If this parameter is NULL, the stack will be dynamically allocated.
stackSize	Number of bytes of stack space allocated to the thread. This value is added to stack to get the initial top of stack address.
priority	Thread priority. The accepted range is 1 through 255. Priority 0 is reserved for the idle thread.
startImmediately	Whether the new thread will start to run automatically. If false, the thread will be created in a suspended state. The constants kArStartThread and kArSuspendThread can be used to better document this parameter value.

◆ Thread() [2/4]

template<class T >

Ar::Thread::Thread	(	const char *	name,
		T *	object,
		void(T::*)()	entry,
		void *	stack,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately = `true`
	)

inline

Constructor to set the thread entry to a member function.

Parameters

name	Name of the thread. If NULL, the thread's name is set to an empty string.
object	Pointer to an instance of class T upon which the entry member function will be invoked when the thread is started.
entry	Member function of class T that will be used as the thread's entry point. The member function must take no parameters and return void.
stack	Pointer to the start of the thread's stack. This should be the stack's bottom, not it's top. If this parameter is NULL, the stack will be dynamically allocated.
stackSize	Number of bytes of stack space allocated to the thread. This value is added to stack to get the initial top of stack address.
priority	Thread priority. The accepted range is 1 through 255. Priority 0 is reserved for the idle thread.
startImmediately	Whether the new thread will start to run automatically. If false, the thread will be created in a suspended state. The constants kArStartThread and kArSuspendThread can be used to better document this parameter value.

◆ Thread() [3/4]

Ar::Thread::Thread	(	const char *	name,
		ar_thread_entry_t	entry,
		void *	param,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately = `true`
	)

inline

Constructor to dynamically allocate the stack.

Parameters

name	Name of the thread. If NULL, the thread's name is set to an empty string.
entry	Thread entry point taking one parameter and returning void.
param	Arbitrary pointer-sized value passed as the single parameter to the thread entry point.
stackSize	Number of bytes of stack space to allocate via `new` to the thread.
priority	Thread priority. The accepted range is 1 through 255. Priority 0 is reserved for the idle thread.
startImmediately	Whether the new thread will start to run automatically. If false, the thread will be created in a suspended state. The constants kArStartThread and kArSuspendThread can be used to better document this parameter value.

◆ Thread() [4/4]

template<class T >

Ar::Thread::Thread	(	const char *	name,
		T *	object,
		void(T::*)()	entry,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately = `true`
	)

inline

Constructor to set the thread entry to a member function, using a dynamic stack.

Parameters

name	Name of the thread. If NULL, the thread's name is set to an empty string.
object	Pointer to an instance of class T upon which the entry member function will be invoked when the thread is started.
entry	Member function of class T that will be used as the thread's entry point. The member function must take no parameters and return void.
stackSize	Number of bytes of stack space to allocate via `new` to the thread.
priority	Thread priority. The accepted range is 1 through 255. Priority 0 is reserved for the idle thread.
startImmediately	Whether the new thread will start to run automatically. If false, the thread will be created in a suspended state. The constants kArStartThread and kArSuspendThread can be used to better document this parameter value.

Member Function Documentation

◆ init() [1/2]

ar_status_t Ar::Thread::init	(	const char *	name,
		ar_thread_entry_t	entry,
		void *	param,
		void *	stack,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately = `true`
	)

Base initialiser.

The thread is in suspended state when this method exits. To make it eligible for execution, call the resume() method.

Parameters

name	Name of the thread. If NULL, the thread's name is set to an empty string.
entry	Thread entry point taking one parameter and returning void.
param	Arbitrary pointer-sized value passed as the single parameter to the thread entry point.
stack	Pointer to the start of the thread's stack. This should be the stack's bottom, not it's top. If this parameter is NULL, the stack will be dynamically allocated.
stackSize	Number of bytes of stack space allocated to the thread. This value is added to stack to get the initial top of stack address.
priority	Thread priority. The accepted range is 1 through 255. Priority 0 is reserved for the idle thread.
startImmediately	Whether the new thread will start to run automatically. If false, the thread will be created in a suspended state. The constants kArStartThread and kArSuspendThread can be used to better document this parameter value.

Return values

kArSuccess	The thread was initialised without error.
kArOutOfMemoryError	Failed to dynamically allocate the stack.

◆ init() [2/2]

template<class T >

ar_status_t Ar::Thread::init	(	const char *	name,
		T *	object,
		void(T::*)()	entry,
		void *	stack,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately = `true`
	)

inline

Initializer to set the thread entry to a member function.

Parameters

name	Name of the thread. If NULL, the thread's name is set to an empty string.
object	Pointer to an instance of class T upon which the entry member function will be invoked when the thread is started.
entry	Member function of class T that will be used as the thread's entry point. The member function must take no parameters and return void.
stack	Pointer to the start of the thread's stack. This should be the stack's bottom, not it's top. If this parameter is NULL, the stack will be dynamically allocated.
stackSize	Number of bytes of stack space allocated to the thread. This value is added to stack to get the initial top of stack address.
priority	Thread priority. The accepted range is 1 through 255. Priority 0 is reserved for the idle thread.
startImmediately	Whether the new thread will start to run automatically. If false, the thread will be created in a suspended state. The constants kArStartThread and kArSuspendThread can be used to better document this parameter value.

Return values

kArSuccess	The thread was initialised without error.
kArOutOfMemoryError	Failed to dynamically allocate the stack.

◆ resume()

void Ar::Thread::resume ( )

inline

Make the thread eligible for execution.

If the thread being resumed has a higher priority than that of the current thread, the scheduler is called to immediately switch threads. In this case the thread being resumed will always become the new current thread. This is because the highest priority thread is always guaranteed to be running, meaning the calling thread was the previous highest priority thread.

Does not enter the scheduler if Ar is not running. Does nothing if the thread is already on the ready list.

Todo:: Deal with all thread states properly.

◆ setPriority()

ar_status_t Ar::Thread::setPriority ( uint8_t priority )

inline

Change the thread's priority.

The scheduler is invoked after the priority is set so that the current thread can be changed to the one with the highest priority. The scheduler is invoked even if there is no new highest priority thread. In this case, control may switch to the next thread with the same priority, assuming there is one.

Does not enter the scheduler if Ar is not running.

Parameters

priority Thread priority level from 1 to 255, where lower numbers have a lower priority. Priority number 0 is not allowed because it is reserved for the idle thread.

Return values

kArSuccess
kArInvalidPriorityError

◆ sleep()

static void Ar::Thread::sleep ( unsigned milliseconds )

inlinestatic

Put the current thread to sleep for a certain amount of time.

Does nothing if Ar is not running.

Parameters

milliseconds The number of milliseconds to sleep the calling thread. A sleep time of 0 is ignored.

◆ sleepUntil()

static void Ar::Thread::sleepUntil ( unsigned wakeup )

inlinestatic

Put the current thread to sleep until a specific time.

Does nothing if Ar is not running.

Parameters

wakeup The wakeup time in milliseconds. If the time is not in the future, i.e., less than or equal to the current value returned by ar_get_millisecond_count(), then the sleep request is ignored.

◆ suspend()

void Ar::Thread::suspend ( )

inline

Put thread in suspended state.

If this method is called from the current thread then the scheduler is entered immediately after putting the thread on the suspended list. Calling suspend() on another thread will not cause the scheduler to switch threads.

Does not enter the scheduler if Ar is not running. Does nothing if the thread is already suspended.

Todo:: Deal with all thread states properly.

◆ threadEntry()

virtual void Ar::Thread::threadEntry ( void * param )

protectedvirtual

Virtual thread entry point.

This is the method that subclasses should override.

Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Thread state

Additional Inherited Members

Constructor & Destructor Documentation

◆ Thread() [1/4]

◆ Thread() [2/4]

◆ Thread() [3/4]

◆ Thread() [4/4]

Member Function Documentation

◆ init() [1/2]

◆ init() [2/2]

◆ resume()

◆ setPriority()

◆ sleep()

◆ sleepUntil()

◆ suspend()

◆ threadEntry()