Collaboration diagram for Threads:

Description

Thread API.

argon_threads

Priorities

Thread priorities range from 0 to 255. Higher values are higher priorities, with 255 being the highest priority. Priority 0 is reserved for the idle thread. The highest priority thread that is ready to run will always get the processor. That means that if there is only one high priority thread, it can starve lower priority threads if it never relinquishes control by sleeping or blocking on a resource. Threads with the same priority will preempt each other in a round robin order every system tick.

Encapsulated thread classes

If you want to fully encapsulate a thread you can create a subclass of Thread that provides its own init() method which calls the original Thread::init(). You can either pass a pointer to a static function to the base init() method, as usual, or you can override the virtual Thread::threadEntry() method. In the latter case, you can simply pass NULL for the entry point to the base init() method. To pass values to the thread function, simply create member variables and set them in your subclass' init() method.Here's an example subclass that uses a member function as the entry point:

class MySubclassThread : public Ar::Thread
{
public:
    ar_status_t init()
    {
        // Pass NULL for the entry point. It's not needed because you are
        // overriding threadEntry() below.
        return Thread::init("my thread", NULL, this, m_stack, sizeof(m_stack), 32);
    }
protected:
    // Static memory for the stack.
    uint8_t m_stack[4096];
    // Override the default Thread implementation.
    virtual void threadEntry()
    {
        // Implement your thread here.
    }
};

Classes
struct	ar_thread_t
	Thread. More...

struct	ar_thread_status_t
	Current status of a thread. More...

class	Ar::Thread
	Preemptive thread class. More...

class	Ar::ThreadWithStack< S >
	Template to create a thread and its stack. More...

Enumerations
enum	_ar_thread_priorities { kArIdleThreadPriority, kArMinThreadPriority, kArMaxThreadPriority }
	Range of priorities for threads. More...

enum	ar_thread_state_t { kArThreadUnknown, kArThreadSuspended, kArThreadReady, kArThreadRunning, kArThreadBlocked, kArThreadSleeping, kArThreadDone }
	Potential thread states. More...

Function types
typedef void(*	ar_thread_entry_t) (void *param)
	Prototype for the thread entry point. More...

Threads
ar_status_t	ar_thread_create (ar_thread_t thread, const char name, ar_thread_entry_t entry, void param, void stack, unsigned stackSize, uint8_t priority, bool startImmediately)
	Create a new thread. More...

ar_status_t	ar_thread_delete (ar_thread_t *thread)
	Delete a thread. More...

ar_status_t	ar_thread_suspend (ar_thread_t *thread)
	Put thread in suspended state. More...

ar_status_t	ar_thread_resume (ar_thread_t *thread)
	Make the thread eligible for execution. More...

ar_thread_state_t	ar_thread_get_state (ar_thread_t *thread)
	Return the current state of the thread. More...

uint8_t	ar_thread_get_priority (ar_thread_t *thread)
	Return the thread's current priority. More...

ar_status_t	ar_thread_set_priority (ar_thread_t *thread, uint8_t newPriority)
	Change a thread's priority. More...

ar_thread_t *	ar_thread_get_current (void)
	Returns the currently running thread object. More...

ar_runloop_t *	ar_thread_get_runloop (ar_thread_t *thread)
	Get the runloop currently associated with the given thread. More...

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

void	ar_thread_sleep_until (uint32_t wakeup)
	Put the current thread to sleep until a specific time. More...

const char *	ar_thread_get_name (ar_thread_t *thread)
	Get the thread's name. More...

uint32_t	ar_thread_get_load (ar_thread_t *thread)
	Get the amount of CPU time the thread is using. More...

uint32_t	ar_thread_get_stack_used (ar_thread_t *thread)
	Get the maximum stack usage of the specified thread. More...

uint32_t	ar_thread_get_report (ar_thread_status_t report[], uint32_t maxEntries)
	Get a report of all thread's status. More...

Class Documentation

◆ ar_thread_status_t

struct ar_thread_status_t

Class Members
uint32_t	m_cpu	Per mille CPU usage of the thread over the last sampling period, with a range of 1-1000.
uint32_t	m_maxStackUsed	Maximum number of bytes used in the thread's stack.
const char *	m_name	Thread's name.
uint32_t	m_stackSize	Total bytes allocated to the thread's stack.
ar_thread_state_t	m_state	Current thread state.
ar_thread_t *	m_thread	Pointer to the thread's structure.
uint32_t	m_uniqueId	Unique ID for this thread.

Typedef Documentation

◆ ar_thread_entry_t

typedef void(* ar_thread_entry_t) (void *param)

Prototype for the thread entry point.

Enumeration Type Documentation

◆ _ar_thread_priorities

enum _ar_thread_priorities

Range of priorities for threads.

Enumerator
kArIdleThreadPriority	The idle thread's priority. No other thread is allowed to have this priority.
kArMinThreadPriority	Priority value for the lowest priority user thread.
kArMaxThreadPriority	Priority value for the highest priority user thread.

◆ ar_thread_state_t

enum ar_thread_state_t

Potential thread states.

Enumerator
kArThreadUnknown	Hopefully a thread is never in this state.
kArThreadSuspended	Thread is not eligible for execution.
kArThreadReady	Thread is eligible to be run.
kArThreadRunning	The thread is currently running.
kArThreadBlocked	The thread is blocked on another object.
kArThreadSleeping	Thread is sleeping.
kArThreadDone	Thread has exited.

Function Documentation

◆ ar_thread_create()

ar_status_t ar_thread_create	(	ar_thread_t *	thread,
		const char *	name,
		ar_thread_entry_t	entry,
		void *	param,
		void *	stack,
		unsigned	stackSize,
		uint8_t	priority,
		bool	startImmediately
	)

Create a new thread.

The state of the new thread is determined by the startImmediately parameter. If true, the thread is created in the ready state. Otherwise, the thread is suspended when this function exits. In this case, to make it eligible for execution you must call the ar_thread_resume() function. When startImmediately is true, the new thread may start execution before this function returns.

Parameters

thread	Pointer to the thread structure.
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.
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.

Returns: kArSuccess The thread was initialised without error.

◆ ar_thread_delete()

ar_status_t ar_thread_delete ( ar_thread_t * thread )

Delete a thread.

Parameters

thread Pointer to the thread structure.

◆ ar_thread_get_current()

ar_thread_t* ar_thread_get_current ( void )

Returns the currently running thread object.

Returns: Pointer to the current thread's structure.

◆ ar_thread_get_load()

uint32_t ar_thread_get_load ( ar_thread_t * thread )

Get the amount of CPU time the thread is using.

Thread CPU usage is computed once every second for all threads.

Returns: Per mille of CPU load for the given thread. Value is 0-1000.

◆ ar_thread_get_name()

const char* ar_thread_get_name ( ar_thread_t * thread )

Get the thread's name.

Returns: Pointer to the name of the thread.

◆ ar_thread_get_priority()

uint8_t ar_thread_get_priority ( ar_thread_t * thread )

Return the thread's current priority.

Parameters

thread Pointer to the thread structure.

◆ ar_thread_get_report()

uint32_t ar_thread_get_report	(	ar_thread_status_t	report[],
		uint32_t	maxEntries
	)

Get a report of all thread's status.

Parameters

[out]	Report	array to be filled in.
	maxEntries	Maximum number of thread status that can be placed into report.

Returns: Actual number of threads filled in to report.

◆ ar_thread_get_runloop()

ar_runloop_t* ar_thread_get_runloop ( ar_thread_t * thread )

Get the runloop currently associated with the given thread.

Returns: Pointer to the runloop runnning on the thread, if there is one. If there is not an associated runloop, then NULL will be returned.

◆ ar_thread_get_stack_used()

uint32_t ar_thread_get_stack_used ( ar_thread_t * thread )

Get the maximum stack usage of the specified thread.

Parameters

thread The thread to inspect.

Returns: Maximum number of bytes used in the thread's stack, rounded down to the nearest word. If the thread has overflowed its stack, then 0 will be returned.

◆ ar_thread_get_state()

ar_thread_state_t ar_thread_get_state ( ar_thread_t * thread )

Return the current state of the thread.

Parameters

thread Pointer to the thread structure.

◆ ar_thread_resume()

ar_status_t ar_thread_resume ( ar_thread_t * thread )

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.

Parameters

thread Pointer to the thread structure.

◆ ar_thread_set_priority()

ar_status_t ar_thread_set_priority	(	ar_thread_t *	thread,
		uint8_t	newPriority
	)

Change a 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

thread	Pointer to the thread structure.
newPriority	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

◆ ar_thread_sleep()

void ar_thread_sleep ( uint32_t milliseconds )

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

Does nothing if Ar is not running.

A sleeping thread can be woken early by calling ar_thread_resume().

Parameters

milliseconds The number of milliseconds to sleep the calling thread. A sleep time of 0 is ignored. If kArInfiniteTimeout is passed for the sleep time, the thread will simply be suspended.

◆ ar_thread_sleep_until()

void ar_thread_sleep_until ( uint32_t wakeup )

Put the current thread to sleep until a specific time.

Does nothing if Ar is not running.

A sleeping thread can be woken early by calling ar_thread_resume().

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.

◆ ar_thread_suspend()

ar_status_t ar_thread_suspend ( ar_thread_t * thread )

Put thread in suspended state.

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

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

Parameters

thread Pointer to the thread structure.

Description

argon_threads

Priorities

Encapsulated thread classes

Classes

Enumerations

Function types

Threads

Class Documentation

◆ ar_thread_status_t

Typedef Documentation

◆ ar_thread_entry_t

Enumeration Type Documentation

◆ _ar_thread_priorities

◆ ar_thread_state_t

Function Documentation

◆ ar_thread_create()

◆ ar_thread_delete()

◆ ar_thread_get_current()

◆ ar_thread_get_load()

◆ ar_thread_get_name()

◆ ar_thread_get_priority()

◆ ar_thread_get_report()

◆ ar_thread_get_runloop()

◆ ar_thread_get_stack_used()

◆ ar_thread_get_state()

◆ ar_thread_resume()

◆ ar_thread_set_priority()

◆ ar_thread_sleep()

◆ ar_thread_sleep_until()

◆ ar_thread_suspend()