µOS++ IIIe Reference 7.0.0
The third edition of µOS++, a POSIX inspired open source framework, written in C++
Loading...
Searching...
No Matches
os::rtos::thread Class Reference

POSIX compliant thread, using the default RTOS allocator. More...

#include <cmsis-plus/rtos/os.h>

+ Inheritance diagram for os::rtos::thread:

Classes

class  attributes
 Thread attributes. More...
 
class  context
 Thread context. More...
 
struct  priority
 Thread priorities. More...
 
class  stack
 Thread stack. More...
 
struct  state
 Thread states. More...
 
class  statistics
 Thread statistics. More...
 

Public Types

using allocator_type = memory::allocator< stack::allocation_element_t >
 Default RTOS allocator.
 
using func_args_t = _func_args_t
 Type of thread function arguments.
 
using func_t = void *(*)(func_args_t args)
 Type of thread function.
 
using priority_t = uint8_t
 Type of variables holding thread priorities.
 
using state_t = uint8_t
 Type of variables holding thread states.
 

Public Member Functions

Constructors & Destructor
 thread (func_t function, func_args_t args, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
 Construct a thread object instance.
 
 thread (const char *name, func_t function, func_args_t args, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
 Construct a named thread object instance.
 
virtual ~thread ()
 Destruct the thread object instance.
 
Operators
bool operator== (const thread &rhs) const
 Compare threads.
 
Public Member Functions
result_t cancel (void)
 Cancel thread execution.
 
result_t detach (void)
 Detach a thread.
 
result_t join (void **exit_ptr=nullptr)
 Wait for thread termination.
 
result_t priority (priority_t prio)
 Set the assigned scheduling priority.
 
result_t priority_inherited (priority_t prio)
 Set the inherited scheduling priority.
 
priority_t priority (void)
 Get the current scheduling priority.
 
priority_t priority_inherited (void)
 Get the inherited scheduling priority.
 
bool interrupted (void)
 Check if interrupted.
 
bool interrupt (bool interrupt=true)
 Set the interrupt flag, possibly interrupting the thread.
 
state_t state (void) const
 Get thread scheduler state.
 
void resume (void)
 Resume the thread.
 
void * function_args (void) const
 Get the thread function arguments.
 
os_thread_user_storage_t * user_storage (void)
 Get the user storage.
 
result_t flags_raise (flags::mask_t mask, flags::mask_t *oflags=nullptr)
 Raise thread event flags.
 
result_t kill (void)
 Force thread termination.
 
thread::stackstack (void)
 Get the thread context stack.
 
thread::statisticsstatistics (void)
 
Public Member Functions
const char * name (void) const
 Get object name.
 

Static Public Member Functions

static bool is_constructed (const thread &thread)
 Check if the thread is constructed.
 
Operators
static void * operator new (std::size_t bytes)
 Allocate space for a new object instance using the RTOS system allocator.
 
static void * operator new (std::size_t bytes, void *ptr)
 Emplace a new object instance.
 
static void * operator new[] (std::size_t bytes)
 Allocate space for an array of new object instances using the RTOS system allocator.
 
static void * operator new[] (std::size_t bytes, void *ptr)
 Emplace an array of new object instances.
 
static void operator delete (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated object instance. using the RTOS system allocator.
 
static void operator delete[] (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.
 

Public Attributes

int errno_ = 0
 

Static Public Attributes

static const attributes initializer
 Default thread initialiser.
 

Detailed Description

POSIX compliant thread, using the default RTOS allocator.

µOS++ threads are inspired by POSIX threads; they support functions that terminate and a simplified version of signals as event flags.

Example
#include <cstdlib>
using namespace os::rtos;
// Thread function.
void*
func(void* args)
{
// Do something.
...
return nullptr;
}
int
os_main(int argc, char* argv[])
{
// Construct new thread, with function and no arguments.
thread th { func, nullptr };
// Do something.
// Wait for thread to terminate.
this_thread::join(th);
return 0;
}
POSIX compliant thread, using the default RTOS allocator.
Definition os-thread.h:250
int os_main(int argc, char *argv[])
Application entry point, running on the main thread context.
RTOS namespace.
Definition os-flags.h:38
Single file µOS++ RTOS definitions.
POSIX compatibility
Inspired by pthread_t from <pthread.h> (IEEE Std 1003.1, 2013 Edition).

Definition at line 249 of file os-thread.h.

Member Typedef Documentation

◆ allocator_type

Default RTOS allocator.

Definition at line 1014 of file os-thread.h.

◆ func_args_t

using os::rtos::thread::func_args_t = _func_args_t

Type of thread function arguments.

Useful to cast other similar types to silence possible compiler warnings.

Definition at line 412 of file os-thread.h.

◆ func_t

using os::rtos::thread::func_t = void* (*) (func_args_t args)

Type of thread function.

Useful to cast other similar types to silence possible compiler warnings.

Definition at line 420 of file os-thread.h.

◆ state_t

using os::rtos::thread::state_t = uint8_t

Type of variables holding thread states.

Definition at line 356 of file os-thread.h.

Constructor & Destructor Documentation

◆ thread() [1/2]

thread::thread ( func_t  function,
func_args_t  args,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)

Construct a thread object instance.

Parameters
[in]functionPointer to thread function.
[in]argsPointer to thread function arguments.
[in]attrReference to attributes.
[in]allocatorReference to allocator. Default a local temporary instance.

This constructor shall initialise a thread object with attributes referenced by attr. If the attributes specified by attr are modified later, the thread attributes shall not be affected. Upon successful initialisation, the state of the thread object shall become initialised, and the thread is added to the ready list.

Only the thread object itself may be used for running the function. It is not allowed to make copies of thread objects.

In cases where default thread attributes are appropriate, the variable thread::initializer can be used to initialise threads. The effect shall be equivalent to creating a thread object with the default constructor.

The thread is created to execute function with args as its sole argument. If the function returns, the effect shall be as if there was an implicit call to exit() using the return value of function as the exit code. Note that the thread in which main() was originally invoked differs from this. When it returns from main(), the effect shall be as if there was an implicit call to exit() using the return value of main() as the exit code.

If the attributes define a stack area (via th_stack_address and th_stack_size_bytes), that stack is used, otherwise the stack is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

If the attr attributes are modified after the thread creation, the thread attributes shall not be affected.

POSIX compatibility
Inspired by pthread_create() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 345 of file os-thread.cpp.

◆ thread() [2/2]

thread::thread ( const char *  name,
func_t  function,
func_args_t  args,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)

Construct a named thread object instance.

Parameters
[in]namePointer to name.
[in]functionPointer to thread function.
[in]argsPointer to thread function arguments.
[in]attrReference to attributes.
[in]allocatorReference to allocator. Default a local temporary instance.

This constructor shall initialise a named thread object with attributes referenced by attr. If the attributes specified by attr are modified later, the thread attributes shall not be affected. Upon successful initialisation, the state of the thread object shall become initialised, and the thread is added to the ready list.

Only the thread object itself may be used for running the function. It is not allowed to make copies of thread objects.

In cases where default thread attributes are appropriate, the variable thread::initializer can be used to initialise threads. The effect shall be equivalent to creating a thread object with the default constructor.

The thread is created to execute function with args as its sole argument. If the function returns, the effect shall be as if there was an implicit call to exit() using the return value of function as the exit code. Note that the thread in which main() was originally invoked differs from this. When it returns from main(), the effect shall be as if there was an implicit call to exit() using the return value of main() as the exit code.

If the attributes define a stack area (via th_stack_address and th_stack_size_bytes), that stack is used, otherwise the stack is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

If the attr attributes are modified after the thread creation, the thread attributes shall not be affected.

POSIX compatibility
Inspired by pthread_create() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 396 of file os-thread.cpp.

◆ ~thread()

thread::~thread ( )
virtual

Destruct the thread object instance.

This destructor shall destroy the thread object; the object becomes, in effect, uninitialised. An implementation may cause the destructor to set the object to an invalid value.

If the stack was dynamically allocated, it is deallocated using the same allocator.

POSIX compatibility
No POSIX similar functionality identified.
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 577 of file os-thread.cpp.

Member Function Documentation

◆ cancel()

result_t thread::cancel ( void  )

Cancel thread execution.

Parameters
None.
Return values
result::okThe cancel request was sent to the thread.
EPERMCannot be invoked from an Interrupt Service Routines.

The cancel() function shall not return an error code of EINTR. If an implementation detects use of a thread ID after the end of its lifetime, it is recommended that the function should fail and report an ESRCH error. error number is returned.

Todo:
Implement it properly (thread interruption is not yet fully implemented).
POSIX compatibility
Inspired by pthread_cancel() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 967 of file os-thread.cpp.

◆ detach()

result_t thread::detach ( void  )

Detach a thread.

Parameters
None.
Return values
result::okThe thread was detached.
EPERMCannot be invoked from an Interrupt Service Routines.

Indicate to the implementation that storage for the thread thread can be reclaimed when that thread terminates. If thread has not terminated, detach() shall not cause it to terminate. The behaviour is undefined if the value specified by the thread argument to detach() does not refer to a joinable thread.

POSIX compatibility
Inspired by pthread_detach() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).

The detach() function shall not return an error code of EINTR.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 861 of file os-thread.cpp.

◆ flags_raise()

result_t thread::flags_raise ( flags::mask_t  mask,
flags::mask_t oflags = nullptr 
)

Raise thread event flags.

Parameters
[in]maskThe OR-ed flags to raise.
[out]oflagsOptional pointer where to store the previous flags; may be nullptr.
Return values
result::okThe flags were raised.
EINVALThe mask is zero.
EPERMCannot be invoked from an Interrupt Service Routines.

Set more bits in the thread current event flags mask. Use OR at bit-mask level. Wake-up the thread to evaluate the event flags.

Note
Can be invoked from Interrupt Service Routines.

Definition at line 1281 of file os-thread.cpp.

◆ function_args()

void * thread::function_args ( void  ) const
inline

Get the thread function arguments.

Parameters
None.
Returns
Pointer to arguments.
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 2358 of file os-thread.h.

◆ interrupt()

bool thread::interrupt ( bool  interrupt = true)

Set the interrupt flag, possibly interrupting the thread.

Parameters
[in]interruptFlag.
Returns
The previous value of the interrupt flag.

If the interrupt flag is true, threads waiting for an event are notified immediately (actually as soon as the thread priority allows it to run).

After the thread detects the interrupted condition, it must clear the interrupted flag.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 992 of file os-thread.cpp.

◆ interrupted()

bool thread::interrupted ( void  )
inline

Check if interrupted.

Parameters
None.
Return values
trueThe thread was interrupted.
falseThe thread was not interrupted.
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 2367 of file os-thread.h.

◆ is_constructed()

bool thread::is_constructed ( const thread thread)
static

Check if the thread is constructed.

Parameters
[in]threadReference to thread object instance.
Returns
true if the thread was constructed and not yet destructed.

Check the thread status to determine if the thread is already in a constructed state, which means it was constructed and not yet destructed. This is useful for threads constructed via the C API or in C++ via placement new, to avoid constructing them when already constructed.

Note
For this function to be accurate before the first invocation, it is necessary for the thread to start with the memory cleared, for example via a memset().
Todo:
Consider adding a separate member with the magic, for improved reliability.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 293 of file os-thread.cpp.

◆ join()

result_t thread::join ( void **  exit_ptr = nullptr)

Wait for thread termination.

Parameters
[in]exit_ptrPointer to thread exit value. (Optional, may be nullptr).
Return values
result::okThe thread was terminated.
EPERMCannot be invoked from an Interrupt Service Routines.

Suspend execution of the calling thread until the target thread terminates, unless the target thread has already terminated. On return from a successful join() call with a non-NULL exit_ptr argument, the value passed to exit() by the terminating thread shall be made available in the location referenced by exit_ptr. When a join() returns successfully, the target thread has been terminated. The results of multiple simultaneous calls to join() specifying the same target thread are undefined. If the thread calling join() is cancelled, then the target thread shall not be detached.

POSIX compatibility
Inspired by pthread_join() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).

The join() function may fail if: [EDEADLK] A deadlock was detected.

The join() function shall not return an error code of [EINTR].

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 916 of file os-thread.cpp.

◆ kill()

result_t thread::kill ( void  )

Force thread termination.

Parameters
None.
Return values
result::okThe tread was terminated.
POSIX compatibility
Inspired by pthread_kill() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1199 of file os-thread.cpp.

◆ name()

const char * os::rtos::internal::object_named::name ( void  ) const
inlineinherited

Get object name.

Parameters
None.
Returns
A null terminated string.

All objects return a non-null string; anonymous objects return "-".

Note
Can be invoked from Interrupt Service Routines.

Definition at line 759 of file os-decls.h.

◆ operator delete()

void os::rtos::internal::object_named_system::operator delete ( void *  ptr,
std::size_t  bytes 
)
inlinestaticinherited

Deallocate the dynamically allocated object instance. using the RTOS system allocator.

Parameters
ptrPointer to object.
bytesNumber of bytes to deallocate.
Returns
Nothing.

The deallocation function (3.7.4.2) called by a delete-expression to render the value of ptr invalid.

ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new() which has not been invalidated by an intervening call to operator delete(void*).

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 122 of file os-inlines.h.

◆ operator delete[]()

void os::rtos::internal::object_named_system::operator delete[] ( void *  ptr,
std::size_t  bytes 
)
inlinestaticinherited

Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.

Parameters
ptrPointer to array of objects.
bytesNumber of bytes to deallocate.
Returns
Nothing.

The deallocation function (3.7.4.2) called by the array form of a delete-expression to render the value of ptr invalid.

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 143 of file os-inlines.h.

◆ operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes)
inlinestaticinherited

Allocate space for a new object instance using the RTOS system allocator.

Parameters
bytesNumber of bytes to allocate.
Returns
Pointer to allocated object.

The allocation function (3.7.4.1) called by a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 44 of file os-inlines.h.

◆ operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes,
void *  ptr 
)
inlinestaticinherited

Emplace a new object instance.

Parameters
bytesNumber of bytes to emplace.
ptrPointer to location to emplace the object.
Returns
Pointer to emplaced object.

The allocation function (3.7.4.1) called by a placement new-expression to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 81 of file os-inlines.h.

◆ operator new[]() [1/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes)
inlinestaticinherited

Allocate space for an array of new object instances using the RTOS system allocator.

Parameters
bytesNumber of bytes to allocate.
Returns
Pointer to allocated array.

The allocation function (3.7.4.1) called by the array form of a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 62 of file os-inlines.h.

◆ operator new[]() [2/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes,
void *  ptr 
)
inlinestaticinherited

Emplace an array of new object instances.

Parameters
bytesNumber of bytes to emplace.
ptrPointer to location to emplace the object.
Returns
Pointer to emplaced array.

The allocation function (3.7.4.1) called by the array form of a placement new-expression to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 98 of file os-inlines.h.

◆ operator==()

bool thread::operator== ( const thread rhs) const
inline

Compare threads.

Return values
trueThe given thread is the same as this thread.
falseThe threads are different.

Identical threads should have the same memory address.

Compatible with POSIX pthread_equal(). http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_equal.html

Definition at line 2340 of file os-thread.h.

◆ priority() [1/2]

Set the assigned scheduling priority.

Parameters
[in]prioNew priority.
Return values
result::okThe priority was set.
EPERMCannot be invoked from an Interrupt Service Routines.
EINVALThe value of prio is invalid for the scheduling policy of the specified thread.

Set the scheduling priority for the thread to the value given by prio.

If an implementation detects use of a thread ID after the end of its lifetime, it is recommended that the function should fail and report an ESRCH error.

The priority() function shall not return an error code of EINTR.

POSIX compatibility
Inspired by pthread_setschedprio() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 715 of file os-thread.cpp.

◆ priority() [2/2]

Get the current scheduling priority.

Parameters
None.
Returns
The thread priority.
POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 661 of file os-thread.cpp.

◆ priority_inherited() [1/2]

result_t thread::priority_inherited ( priority_t  prio)

Set the inherited scheduling priority.

Parameters
[in]prioNew priority.
Return values
result::okThe priority was set.
EPERMCannot be invoked from an Interrupt Service Routines.
EINVALThe value of prio is invalid for the scheduling policy of the specified thread.

Set the scheduling inherited priority for the thread to the value given by prio.

If an implementation detects use of a thread ID after the end of its lifetime, it is recommended that the function should fail and report an ESRCH error.

The priority_inherited() function shall not return an error code of EINTR.

POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 783 of file os-thread.cpp.

◆ priority_inherited() [2/2]

thread::priority_t thread::priority_inherited ( void  )

Get the inherited scheduling priority.

Parameters
None.
Returns
The thread inherited priority. May be priority::none.
POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 687 of file os-thread.cpp.

◆ resume()

void thread::resume ( void  )

Resume the thread.

Parameters
None.
Returns
Nothing.

Internal, used in the implementation of synchronisation objects.

POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 612 of file os-thread.cpp.

◆ stack()

class thread::stack & thread::stack ( void  )
inline

Get the thread context stack.

Parameters
None.
Returns
A reference to the context stack object instance.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 2445 of file os-thread.h.

◆ state()

thread::state_t thread::state ( void  ) const
inline

Get thread scheduler state.

Parameters
None.
Returns
Thread scheduler state.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 2349 of file os-thread.h.

◆ statistics()

class thread::statistics & thread::statistics ( void  )
inline
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 2456 of file os-thread.h.

◆ user_storage()

os_thread_user_storage_t * thread::user_storage ( void  )
inline

Get the user storage.

Parameters
None.
Returns
The address of the thread user storage.

The user storage is a custom structure defined in <os-app-config.h>, which is added to each and every thread storage. Applications can store here any data.

Inspired by (actually a generalisation of) µC-OS III task user registers and FreeRTOS thread local storage, which proved useful when implementing CMSIS+ over FreeRTOS.

Note
Available only when OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE is defined.
Can be invoked from Interrupt Service Routines.

Definition at line 2392 of file os-thread.h.

Member Data Documentation

◆ errno_

int os::rtos::thread::errno_ = 0

Definition at line 255 of file os-thread.h.

◆ initializer

const thread::attributes thread::initializer
static

Default thread initialiser.

This variable is used by the default constructor.

Definition at line 1007 of file os-thread.h.


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