µOS++ IIIe Reference  v6.3.15
“Perfekt ist nicht gut genug”
The third edition of µOS++, a POSIX inspired open source system, written in C++.
os::rtos::thread_allocated< Allocator > Class Template Reference

Template of a POSIX compliant thread with allocator. More...

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

Inherits os::rtos::thread.

Public Types

using allocator_type = Allocator
 Standard allocator type definition. More...
 
using func_args_t = _func_args_t
 Type of thread function arguments. More...
 
using func_t = void *(*)(func_args_t args)
 Type of thread function. More...
 
using priority_t = uint8_t
 Type of variables holding thread priorities. More...
 
using state_t = uint8_t
 Type of variables holding thread states. More...
 

Public Member Functions

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

Static Public Member Functions

Operators
static void * operator new (std::size_t bytes)
 Allocate space for a new object instance using the RTOS system allocator. More...
 
static void * operator new (std::size_t bytes, void *ptr)
 Emplace a new object instance. More...
 
static void * operator new[] (std::size_t bytes)
 Allocate space for an array of new object instances using the RTOS system allocator. More...
 
static void * operator new[] (std::size_t bytes, void *ptr)
 Emplace an array of new object instances. More...
 
static void operator delete (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated object instance. using the RTOS system allocator. More...
 
static void operator delete[] (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated array of object. instances using the RTOS system allocator. More...
 

Public Attributes

int errno_ = 0
 

Static Public Attributes

static const attributes initializer
 Default thread initialiser. More...
 

Detailed Description

template<typename Allocator = memory::allocator<void*>>
class os::rtos::thread_allocated< Allocator >

Template of a POSIX compliant thread with allocator.

Template Parameters
AllocatorStandard allocator used to allocate the stack area.

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

Types

◆ allocator_type

template<typename Allocator = memory::allocator<void*>>
using os::rtos::thread_allocated< Allocator >::allocator_type = Allocator

Standard allocator type definition.

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

◆ func_args_t

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

Type of thread function arguments.

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

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

◆ func_t

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

Type of thread function.

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

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

◆ state_t

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

Type of variables holding thread states.

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

Constructor & Destructor Documentation

◆ thread_allocated() [1/2]

template<typename Allocator >
os::rtos::thread_allocated< Allocator >::thread_allocated ( func_t  function,
func_args_t  args,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)
inline

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).

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 2471 of file os-thread.h.

◆ thread_allocated() [2/2]

template<typename Allocator >
os::rtos::thread_allocated< Allocator >::thread_allocated ( 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).

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 2522 of file os-thread.h.

◆ ~thread_allocated()

template<typename Allocator >
os::rtos::thread_allocated< Allocator >::~thread_allocated ( )
overridevirtual

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.

The stack is deallocated using the same allocator.

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

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

Member Function Documentation

◆ cancel()

result_t thread::cancel ( void  )
inherited

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 911 of file os-thread.cpp.

◆ detach()

result_t thread::detach ( void  )
inherited

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 804 of file os-thread.cpp.

◆ flags_raise()

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

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 1206 of file os-thread.cpp.

◆ function_args()

void * thread::function_args ( void  ) const
inlineinherited

Get the thread function arguments.

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

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

◆ interrupt()

bool thread::interrupt ( bool  interrupt = true)
inherited

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 936 of file os-thread.cpp.

◆ interrupted()

bool thread::interrupted ( void  )
inlineinherited

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 2326 of file os-thread.h.

◆ join()

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

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 859 of file os-thread.cpp.

◆ kill()

result_t thread::kill ( void  )
inherited

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 1127 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 760 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 134 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 155 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 56 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 93 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 74 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 110 of file os-inlines.h.

◆ operator==()

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

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 2293 of file os-thread.h.

◆ priority() [1/2]

result_t thread::priority ( priority_t  prio)
inherited

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 658 of file os-thread.cpp.

◆ priority() [2/2]

thread::priority_t thread::priority ( void  )
inherited

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 602 of file os-thread.cpp.

◆ priority_inherited() [1/2]

result_t thread::priority_inherited ( priority_t  prio)
inherited

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 726 of file os-thread.cpp.

◆ priority_inherited() [2/2]

thread::priority_t thread::priority_inherited ( void  )
inherited

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 630 of file os-thread.cpp.

◆ resume()

void thread::resume ( void  )
inherited

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 551 of file os-thread.cpp.

◆ stack()

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

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 2396 of file os-thread.h.

◆ state()

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

Get thread scheduler state.

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

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

◆ statistics()

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

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

◆ user_storage()

os_thread_user_storage_t * thread::user_storage ( void  )
inlineinherited

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 2351 of file os-thread.h.

Member Data Documentation

◆ errno_

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

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

◆ initializer

const thread::attributes thread::initializer
staticinherited

Default thread initialiser.

This variable is used by the default constructor.

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


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