Mistake on this page?
Report an issue in GitHub or email us
Public Types | Public Member Functions | Static Public Member Functions
Thread Class Reference

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

#include <Thread.h>

Inheritance diagram for Thread:
NonCopyable< Thread >

Public Types

Public Member Functions

 Thread (osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=NULL, const char *name=NULL)
 Allocate a new thread without starting execution. More...
 
 Thread (uint32_t tz_module, osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=NULL, const char *name=NULL)
 Allocate a new thread without starting execution. More...
 
 Thread (mbed::Callback< void()> task, osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=NULL)
 Create a new thread, and start it executing the specified function. More...
 
template<typename T >
 Thread (T *argument, void(T::*task)(), osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=NULL)
 Create a new thread, and start it executing the specified function. More...
 
template<typename T >
 Thread (T *argument, void(*task)(T *), osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=NULL)
 Create a new thread, and start it executing the specified function. More...
 
 Thread (void(*task)(void const *argument), void *argument=NULL, osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=NULL)
 Create a new thread, and start it executing the specified function. More...
 
osStatus start (mbed::Callback< void()> task)
 Starts a thread executing the specified function. More...
 
template<typename T , typename M >
osStatus start (T *obj, M method)
 Starts a thread executing the specified function. More...
 
osStatus join ()
 Wait for thread to terminate. More...
 
osStatus terminate ()
 Terminate execution of a thread and remove it from Active Threads. More...
 
osStatus set_priority (osPriority priority)
 Set priority of an active thread. More...
 
osPriority get_priority () const
 Get priority of an active thread. More...
 
uint32_t flags_set (uint32_t flags)
 Set the specified Thread Flags for the thread. More...
 
int32_t signal_set (int32_t signals)
 Set the specified Thread Flags for the thread. More...
 
State get_state () const
 State of this Thread. More...
 
uint32_t stack_size () const
 Get the total stack memory size for this Thread. More...
 
uint32_t free_stack () const
 Get the currently unused stack memory for this Thread. More...
 
uint32_t used_stack () const
 Get the currently used stack memory for this Thread. More...
 
uint32_t max_stack () const
 Get the maximum stack memory usage to date for this Thread. More...
 
const char * get_name () const
 Get thread name. More...
 
osThreadId_t get_id () const
 Get thread id. More...
 
virtual ~Thread ()
 Thread destructor. More...
 

Static Public Member Functions

static int32_t signal_clr (int32_t signals)
 Clears the specified Thread Flags of the currently running thread. More...
 
static osEvent signal_wait (int32_t signals, uint32_t millisec=osWaitForever)
 Wait for one or more Thread Flags to become signaled for the current RUNNING thread. More...
 
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. More...
 
static osStatus wait_until (uint64_t millisec)
 Wait until a specified time in millisec The specified time is according to Kernel::get_ms_count(). More...
 
static osStatus yield ()
 Pass control to next thread that is in state READY. More...
 
static osThreadId gettid ()
 Get the thread id of the current running thread. More...
 
static void attach_idle_hook (void(*fptr)(void))
 Attach a function to be called by the RTOS idle task. More...
 
static void attach_terminate_hook (void(*fptr)(osThreadId id))
 Attach a function to be called when a task is killed. More...
 

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 85 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 332 of file Thread.h.

Constructor & Destructor Documentation

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

Allocate a new thread without starting execution.

Parameters
priorityinitial priority of the thread function. (default: osPriorityNormal).
stack_sizestack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mempointer to the stack area to be used by this thread (default: NULL).
namename to be used for this thread. It has to stay allocated for the lifetime of the thread (default: NULL)
Note
Default value of tz_module will be MBED_TZ_DEFAULT_ACCESS
You cannot call this function from ISR context.

Definition at line 97 of file Thread.h.

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

Allocate a new thread without starting execution.

Parameters
tz_moduletrustzone 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.
priorityinitial priority of the thread function. (default: osPriorityNormal).
stack_sizestack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mempointer to the stack area to be used by this thread (default: NULL).
namename to be used for this thread. It has to stay allocated for the lifetime of the thread (default: NULL)
Note
You cannot call this function from ISR context.

Definition at line 117 of file Thread.h.

Thread ( mbed::Callback< void()>  task,
osPriority  priority = osPriorityNormal,
uint32_t  stack_size = OS_STACK_SIZE,
unsigned char *  stack_mem = NULL 
)

Create a new thread, and start it executing the specified function.

Parameters
taskfunction to be executed by this thread.
priorityinitial priority of the thread function. (default: osPriorityNormal).
stack_sizestack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mempointer to the stack area to be used by this thread (default: NULL).
Deprecated:
Thread-spawning constructors hide errors. Replaced by thread.start(task).
Thread thread(priority, stack_size, stack_mem);
osStatus status = thread.start(task);
if (status != osOK) {
error("oh no!");
}
Note
You cannot call this function from ISR context.

Definition at line 147 of file Thread.h.

Thread ( T *  argument,
void(T::*)()  task,
osPriority  priority = osPriorityNormal,
uint32_t  stack_size = OS_STACK_SIZE,
unsigned char *  stack_mem = NULL 
)

Create a new thread, and start it executing the specified function.

Parameters
argumentpointer that is passed to the thread function as start argument. (default: NULL).
taskargument to task.
priorityinitial priority of the thread function. (default: osPriorityNormal).
stack_sizestack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mempointer to the stack area to be used by this thread (default: NULL).
Deprecated:
Thread-spawning constructors hide errors. Replaced by thread.start(callback(task, argument)).
Thread thread(priority, stack_size, stack_mem);
osStatus status = thread.start(callback(task, argument));
if (status != osOK) {
error("oh no!");
}
Note
You cannot call this function from ISR context.

Definition at line 179 of file Thread.h.

Thread ( T *  argument,
void(*)(T *)  task,
osPriority  priority = osPriorityNormal,
uint32_t  stack_size = OS_STACK_SIZE,
unsigned char *  stack_mem = NULL 
)

Create a new thread, and start it executing the specified function.

Parameters
argumentpointer that is passed to the thread function as start argument. (default: NULL).
taskargument to task.
priorityinitial priority of the thread function. (default: osPriorityNormal).
stack_sizestack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mempointer to the stack area to be used by this thread (default: NULL).
Deprecated:
Thread-spawning constructors hide errors. Replaced by thread.start(callback(task, argument)).
Thread thread(priority, stack_size, stack_mem);
osStatus status = thread.start(callback(task, argument));
if (status != osOK) {
error("oh no!");
}
Note
You cannot call this function from ISR context.

Definition at line 212 of file Thread.h.

Thread ( void(*)(void const *argument)  task,
void *  argument = NULL,
osPriority  priority = osPriorityNormal,
uint32_t  stack_size = OS_STACK_SIZE,
unsigned char *  stack_mem = NULL 
)

Create a new thread, and start it executing the specified function.

Provided for backwards compatibility

Parameters
taskfunction to be executed by this thread.
argumentpointer that is passed to the thread function as start argument. (default: NULL).
priorityinitial priority of the thread function. (default: osPriorityNormal).
stack_sizestack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
stack_mempointer to the stack area to be used by this thread (default: NULL).
Deprecated:
Thread-spawning constructors hide errors. Replaced by thread.start(callback(task, argument)).
Thread thread(priority, stack_size, stack_mem);
osStatus status = thread.start(callback(task, argument));
if (status != osOK) {
error("oh no!");
}
Note
You cannot call this function from ISR context.

Definition at line 245 of file Thread.h.

virtual ~Thread ( )
virtual

Thread destructor.

Note
You cannot call this function from ISR context.

Member Function Documentation

static void attach_idle_hook ( void(*)(void)  fptr)
static

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

Parameters
fptrpointer to the function to be called
Note
You may call this function from ISR context.
Deprecated:
Static methods affecting system cause confusion. Replaced by Kernel::attach_idle_hook.
static void attach_terminate_hook ( void(*)(osThreadId id)  fptr)
static

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

Parameters
fptrpointer to the function to be called
Note
You may call this function from ISR context.
Deprecated:
Static methods affecting system cause confusion. Replaced by Kernel::attach_thread_terminate_hook.
uint32_t flags_set ( uint32_t  flags)

Set the specified Thread Flags for the thread.

Parameters
flagsspecifies 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.
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.
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.
const char* get_name ( ) const

Get thread name.

Returns
thread name or NULL if the name was not set.
Note
You may call this function from ISR context.
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.
State get_state ( ) const

State of this Thread.

Returns
the State of this Thread
Note
You cannot call this function from ISR context.
static osThreadId gettid ( )
static

Get the thread id of the current running thread.

Returns
thread ID for reference by other functions or NULL in case of error.
Note
You may call this function from ISR context.
Deprecated:
Static methods only affecting current thread cause confusion. Replaced by ThisThread::get_id. Use Thread::get_id for the ID of a specific Thread.
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.
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.
osStatus set_priority ( osPriority  priority)

Set priority of an active thread.

Parameters
prioritynew 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.
static int32_t signal_clr ( int32_t  signals)
static

Clears the specified Thread Flags of the currently running thread.

Parameters
signalsspecifies 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.
Deprecated:
Static methods only affecting current thread cause confusion. Replaced by ThisThread::flags_clear.
int32_t signal_set ( int32_t  signals)

Set the specified Thread Flags for the thread.

Parameters
signalsspecifies 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.
Deprecated:
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.
static osEvent signal_wait ( int32_t  signals,
uint32_t  millisec = osWaitForever 
)
static

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

Parameters
signalswait until all specified signal flags are set or 0 for any single signal flag.
millisectimeout 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.
Deprecated:
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.
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.
osStatus start ( mbed::Callback< void()>  task)

Starts a thread executing the specified function.

Parameters
taskfunction 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.
osStatus start ( T *  obj,
method 
)

Starts a thread executing the specified function.

Parameters
objargument to task
methodfunction to be executed by this thread.
Returns
status code that indicates the execution status of the function.
Deprecated:
The start function does not support cv-qualifiers. Replaced by start(callback(obj, method)).
Note
You cannot call this function from ISR context.

Definition at line 276 of file Thread.h.

osStatus terminate ( )

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.
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.
static osStatus wait ( uint32_t  millisec)
static

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
millisectime delay value
Returns
status code that indicates the execution status of the function.
Note
You cannot call this function from ISR context.
Deprecated:
Static methods only affecting current thread cause confusion. Replaced by ThisThread::sleep_for.
static osStatus wait_until ( uint64_t  millisec)
static

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

Parameters
millisecabsolute 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.
Deprecated:
Static methods only affecting current thread cause confusion. Replaced by ThisThread::sleep_until.
static osStatus yield ( )
static

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.
Deprecated:
Static methods only affecting current thread cause confusion. Replaced by ThisThread::sleep_until.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.