The Thread class allow defining, creating, and controlling thread functions in the system. More...

#include <Thread.h>

Public Types
enum	State { Inactive, Ready, Running, WaitingDelay, WaitingJoin, WaitingThreadFlag, WaitingEventFlag, WaitingMutex, WaitingSemaphore, WaitingMemoryPool, WaitingMessageGet, WaitingMessagePut, WaitingInterval, WaitingOr, WaitingAnd, WaitingMailbox, Deleted }
	State of the Thread. More...
Public Member Functions
	Thread (osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char stack_mem=nullptr, const char name=nullptr)
	Allocate a new thread without starting execution.
	Thread (uint32_t tz_module, osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char stack_mem=nullptr, const char name=nullptr)
	Allocate a new thread without starting execution.
osStatus	start (mbed::Callback< void()> task)
	Starts a thread executing the specified function.
osStatus	join ()
	Wait for thread to terminate.
osStatus	terminate ()
	Terminate execution of a thread and remove it from Active Threads.
osStatus	set_priority (osPriority priority)
	Set priority of an active thread.
osPriority	get_priority () const
	Get priority of an active thread.
uint32_t	flags_set (uint32_t flags)
	Set the specified Thread Flags for the thread.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Other signal_xxx methods have been deprecated in favour of ThisThread::flags functions. ""To match this naming scheme, derived from CMSIS-RTOS2, Thread::flags_set is now provided.") int32_t signal_set(int32_t signals)
	Set the specified Thread Flags for the thread.
State	get_state () const
	State of this Thread.
uint32_t	stack_size () const
	Get the total stack memory size for this Thread.
uint32_t	free_stack () const
	Get the currently unused stack memory for this Thread.
uint32_t	used_stack () const
	Get the currently used stack memory for this Thread.
uint32_t	max_stack () const
	Get the maximum stack memory usage to date for this Thread.
const char *	get_name () const
	Get thread name.
osThreadId_t	get_id () const
	Get thread id.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::flags_clear.") static int32_t signal_clr(int32_t signals)
	Clears the specified Thread Flags of the currently running thread.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::flags_wait_all, ThisThread::flags_wait_all_for, ThisThread::flags_wait_any and ThisThread:wait_any_for.") static osEvent signal_wait(int32_t signals
	Wait for one or more Thread Flags to become signaled for the current RUNNING thread.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::sleep_for.") static osStatus wait(uint32_t millisec)
	Wait for a specified time period in milliseconds Being tick-based, the delay will be up to the specified time - eg for a value of 1 the system waits until the next millisecond tick occurs, leading to a delay of 0-1 milliseconds.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::sleep_until.") static osStatus wait_until(uint64_t millisec)
	Wait until a specified time in millisec The specified time is according to Kernel::get_ms_count().
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::yield.") static osStatus yield()
	Pass control to next thread that is in state READY.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::get_id. Use Thread::get_id for the ID of a specific Thread.") static osThreadId gettid()
	Get the thread id of the current running thread.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods affecting system cause confusion. ""Replaced by Kernel::attach_idle_hook.") static void attach_idle_hook(void(*fptr)(void))
	Attach a function to be called by the RTOS idle task.
	MBED_DEPRECATED_SINCE ("mbed-os-5.10","Static methods affecting system cause confusion. ""Replaced by Kernel::attach_thread_terminate_hook.") static void attach_terminate_hook(void(*fptr)(osThreadId id))
	Attach a function to be called when a task is killed.
virtual	~Thread ()
	Thread destructor.
Private Member Functions
	MBED_DEPRECATED ("Invalid copy construction of a NonCopyable resource.") NonCopyable(const NonCopyable &)
	NonCopyable copy constructor.
	MBED_DEPRECATED ("Invalid copy assignment of a NonCopyable resource.") NonCopyable &operator
	NonCopyable copy assignment operator.

Detailed Description

The Thread class allow defining, creating, and controlling thread functions in the system.

Example:

  #include "mbed.h"
  #include "rtos.h"

  Thread thread;
  DigitalOut led1(LED1);
  volatile bool running = true;

  // Blink function toggles the led in a long running loop
  void blink(DigitalOut *led) {
      while (running) {
          *led = !*led;
          wait(1);
      }
  }

  // Spawns a thread to run blink for 5 seconds
  int main() {
      thread.start(callback(blink, &led1));
      wait(5);
      running = false;
      thread.join();
  }

Note:: Memory considerations: The thread control structures will be created on current thread's stack, both for the mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used). Additionally the stack memory for this thread will be allocated on the heap, if it wasn't supplied to the constructor.; MBED_TZ_DEFAULT_ACCESS (default:0) flag can be used to change the default access of all user threads in non-secure mode. MBED_TZ_DEFAULT_ACCESS set to 1, means all non-secure user threads have access to call secure functions. MBED_TZ_DEFAULT_ACCESS set to 0, means none of the non-secure user thread have access to call secure functions, to give access to particular thread used overloaded constructor with `tz_module` as argument during thread creation.

MBED_TZ_DEFAULT_ACCESS is target specific define, should be set in targets.json file for Cortex-M23/M33 devices.

Definition at line 88 of file Thread.h.

Member Enumeration Documentation

enum State

State of the Thread.

Enumerator:

Inactive	NOT USED.
Ready	Ready to run.
Running	Running.
WaitingDelay	Waiting for a delay to occur.
WaitingJoin	Waiting for thread to join. Only happens when using RTX directly.
WaitingThreadFlag	Waiting for a thread flag to be set.
WaitingEventFlag	Waiting for a event flag to be set.
WaitingMutex	Waiting for a mutex event to occur.
WaitingSemaphore	Waiting for a semaphore event to occur.
WaitingMemoryPool	Waiting for a memory pool.
WaitingMessageGet	Waiting for message to arrive.
WaitingMessagePut	Waiting for message to be send.
WaitingInterval	NOT USED.
WaitingOr	NOT USED.
WaitingAnd	NOT USED.
WaitingMailbox	NOT USED (Mail is implemented as MemoryPool and Queue)
Deleted	The task has been deleted or not started.

Definition at line 188 of file Thread.h.

Constructor & Destructor Documentation

Thread	(	osPriority	priority = `osPriorityNormal`,
		uint32_t	stack_size = `OS_STACK_SIZE`,
		unsigned char *	stack_mem = `nullptr`,
		const char *	name = `nullptr`
	)

Allocate a new thread without starting execution.

Parameters:

priority	initial priority of the thread function. (default: osPriorityNormal).
stack_size	stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mem	pointer to the stack area to be used by this thread (default: nullptr).
name	name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: nullptr)

Note:: Default value of tz_module will be MBED_TZ_DEFAULT_ACCESS; You cannot call this function from ISR context.

Definition at line 100 of file Thread.h.

Thread	(	uint32_t	tz_module,
		osPriority	priority = `osPriorityNormal`,
		uint32_t	stack_size = `OS_STACK_SIZE`,
		unsigned char *	stack_mem = `nullptr`,
		const char *	name = `nullptr`
	)

Allocate a new thread without starting execution.

Parameters:

tz_module	trustzone thread identifier (osThreadAttr_t::tz_module) Context of RTOS threads in non-secure state must be saved when calling secure functions. tz_module ID is used to allocate context memory for threads, and it can be safely set to zero for threads not using secure calls at all. See "TrustZone RTOS Context Management" for more details.
priority	initial priority of the thread function. (default: osPriorityNormal).
stack_size	stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mem	pointer to the stack area to be used by this thread (default: nullptr).
name	name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: nullptr)

Note:: You cannot call this function from ISR context.

Definition at line 120 of file Thread.h.

~Thread ( ) [virtual]

Thread destructor.

Note:: You cannot call this function from ISR context.

Definition at line 397 of file Thread.cpp.

Member Function Documentation

uint32_t flags_set ( uint32_t flags )

Set the specified Thread Flags for the thread.

Parameters:

flags specifies the flags of the thread that should be set.

Returns:: thread flags after setting or osFlagsError in case of incorrect parameters.

Note:: You may call this function from ISR context.

Definition at line 171 of file Thread.cpp.

uint32_t free_stack ( ) const

Get the currently unused stack memory for this Thread.

Returns:: the currently unused stack memory in bytes

Note:: You cannot call this function from ISR context.

Definition at line 262 of file Thread.cpp.

osThreadId_t get_id ( ) const

Get thread id.

Returns:: thread ID for reference by other functions.

Note:: You may call this function from ISR context.

Definition at line 321 of file Thread.cpp.

const char * get_name ( ) const

Get thread name.

Returns:: thread name or nullptr if the name was not set.

Note:: You may call this function from ISR context.

Definition at line 316 of file Thread.cpp.

osPriority get_priority ( ) const

Get priority of an active thread.

Returns:: current priority value of the thread function.

Note:: You cannot call this function from ISR context.

Definition at line 160 of file Thread.cpp.

Thread::State get_state ( ) const

State of this Thread.

Returns:: the State of this Thread

Note:: You cannot call this function from ISR context.

Definition at line 183 of file Thread.cpp.

osStatus join ( )

Wait for thread to terminate.

Returns:: status code that indicates the execution status of the function.

Note:: You cannot call this function from ISR context.

Definition at line 133 of file Thread.cpp.

uint32_t max_stack ( ) const

Get the maximum stack memory usage to date for this Thread.

Returns:: the maximum stack memory usage to date in bytes

Note:: You cannot call this function from ISR context.

Definition at line 294 of file Thread.cpp.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::flags_clear."
	)

Clears the specified Thread Flags of the currently running thread.

Parameters:

signals specifies the signal flags of the thread that should be cleared.

Returns:: signal flags before clearing or osFlagsError in case of incorrect parameters.

Note:: You cannot call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::flags_wait_all	,
		ThisThread::flags_wait_all_for	,
		ThisThread::flags_wait_any and ThisThread:wait_any_for."
	)

Wait for one or more Thread Flags to become signaled for the current RUNNING thread.

Parameters:

signals	wait until all specified signal flags are set or 0 for any single signal flag.
millisec	timeout value. (default: osWaitForever).

Returns:: event flag information or error code.

Note:: if millisec is set to 0 and flag is no set the event carries osOK value.; You cannot call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::sleep_for."
	)

Wait for a specified time period in milliseconds Being tick-based, the delay will be up to the specified time - eg for a value of 1 the system waits until the next millisecond tick occurs, leading to a delay of 0-1 milliseconds.

Parameters:

millisec time delay value

Returns:: status code that indicates the execution status of the function.

Note:: You cannot call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::sleep_until."
	)

Wait until a specified time in millisec The specified time is according to Kernel::get_ms_count().

Parameters:

millisec absolute time in millisec

Returns:: status code that indicates the execution status of the function.

Note:: not callable from interrupt; if millisec is equal to or lower than the current tick count, this returns immediately, either with an error or "osOK".; the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the delay is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, it may return with an immediate error, or wait for the maximum delay.; You cannot call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods affecting system cause confusion. ""Replaced by Kernel::attach_thread_terminate_hook."
	)

Attach a function to be called when a task is killed.

Parameters:

fptr	pointer to the function to be called

Note:: You may call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::get_id. Use Thread::get_id for the ID of a specific Thread."
	)

Get the thread id of the current running thread.

Returns:: thread ID for reference by other functions or nullptr in case of error.

Note:: You may call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods affecting system cause confusion. ""Replaced by Kernel::attach_idle_hook."
	)

Attach a function to be called by the RTOS idle task.

Parameters:

fptr	pointer to the function to be called

Note:: You may call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Static methods only affecting current thread cause confusion. ""Replaced by ThisThread::yield."
	)

Pass control to next thread that is in state READY.

Returns:: status code that indicates the execution status of the function.

Note:: You cannot call this function from ISR context.

MBED_DEPRECATED_SINCE	(	"mbed-os-5.10"	,
		"Other signal_xxx methods have been deprecated in favour of ThisThread::flags functions. ""To match this naming	scheme,
		derived from CMSIS-	RTOS2,
		Thread::flags_set is now provided."
	)

Set the specified Thread Flags for the thread.

Parameters:

signals specifies the signal flags of the thread that should be set.

Returns:: signal flags after setting or osFlagsError in case of incorrect parameters.

Note:: You may call this function from ISR context.

osStatus set_priority ( osPriority priority )

Set priority of an active thread.

Parameters:

priority new priority value for the thread function.

Returns:: status code that indicates the execution status of the function.

Note:: You cannot call this function from ISR context.

Definition at line 149 of file Thread.cpp.

uint32_t stack_size ( ) const

Get the total stack memory size for this Thread.

Returns:: the total stack memory size in bytes

Note:: You cannot call this function from ISR context.

Definition at line 249 of file Thread.cpp.

osStatus start ( mbed::Callback< void()> task )

Starts a thread executing the specified function.

Parameters:

task	function to be executed by this thread.

Returns:: status code that indicates the execution status of the function.

Note:: a thread can only be started once; You cannot call this function ISR context.

Definition at line 72 of file Thread.cpp.

osStatus terminate ( void )

Terminate execution of a thread and remove it from Active Threads.

Returns:: status code that indicates the execution status of the function.

Note:: You cannot call this function from ISR context.

Definition at line 110 of file Thread.cpp.

uint32_t used_stack ( ) const

Get the currently used stack memory for this Thread.

Returns:: the currently used stack memory in bytes

Note:: You cannot call this function from ISR context.

Definition at line 278 of file Thread.cpp.

Type:	Library
Created:	17 Dec 2019
Imports:	79
Forks:	0
Commits:	2
Dependents:	2
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

Thread Class Reference
[Thread class]

Public Types

Public Member Functions

Private Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

Thread Class Reference [Thread class]

Public Types

Public Member Functions

Private Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning

Thread Class Reference
[Thread class]