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::stack &	stack (void)
	Get the thread context stack.

thread::statistics &	statistics (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 <cmsis-plus/rtos/os.h>
#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 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

using os::rtos::thread::allocator_type = memory::allocator<stack::allocation_element_t>

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]	function	Pointer to thread function.
[in]	args	Pointer to thread function arguments.
[in]	attr	Reference to attributes.
[in]	allocator	Reference 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]	name	Pointer to name.
[in]	function	Pointer to thread function.
[in]	args	Pointer to thread function arguments.
[in]	attr	Reference to attributes.
[in]	allocator	Reference 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::ok	The cancel request was sent to the thread.
EPERM	Cannot 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::ok	The thread was detached.
EPERM	Cannot 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]	mask	The OR-ed flags to raise.
[out]	oflags	Optional pointer where to store the previous flags; may be `nullptr`.

Return values

result::ok	The flags were raised.
EINVAL	The mask is zero.
EPERM	Cannot 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] interrupt Flag.

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

true	The thread was interrupted.
false	The 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] thread Reference 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_ptr Pointer to thread exit value. (Optional, may be nullptr).

Return values

result::ok	The thread was terminated.
EPERM	Cannot 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::ok The 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

ptr	Pointer to object.
bytes	Number 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

ptr	Pointer to array of objects.
bytes	Number 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

bytes Number 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

bytes	Number of bytes to emplace.
ptr	Pointer 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

bytes Number 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

bytes	Number of bytes to emplace.
ptr	Pointer 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

true	The given thread is the same as this thread.
false	The 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]

result_t thread::priority ( priority_t prio )

Set the assigned scheduling priority.

Parameters

[in] prio New priority.

Return values

result::ok	The priority was set.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The 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]

thread::priority_t thread::priority ( void )

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] prio New priority.

Return values

result::ok	The priority was set.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The 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:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ allocator_type

◆ func_args_t

◆ func_t

◆ state_t

Constructor & Destructor Documentation

◆ thread() [1/2]

◆ thread() [2/2]

◆ ~thread()

Member Function Documentation

◆ cancel()

◆ detach()

◆ flags_raise()

◆ function_args()

◆ interrupt()

◆ interrupted()

◆ is_constructed()

◆ join()

◆ kill()

◆ name()

◆ operator delete()

◆ operator delete[]()

◆ operator new() [1/2]

◆ operator new() [2/2]

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

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

◆ operator==()

◆ priority() [1/2]

◆ priority() [2/2]

◆ priority_inherited() [1/2]

◆ priority_inherited() [2/2]

◆ resume()

◆ stack()

◆ state()

◆ statistics()

◆ user_storage()

Member Data Documentation

◆ errno_

◆ initializer