Template of a POSIX compliant thread with local stack. More...
#include <cmsis-plus/rtos/os.h>
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_inclusive (func_t function, func_args_t args, const attributes &attr=initializer) | |
Construct a thread object instance. | |
thread_inclusive (const char *name, func_t function, func_args_t args, const attributes &attr=initializer) | |
Construct a named thread object instance. | |
virtual | ~thread_inclusive () override |
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. | |
priority_t | priority (void) |
Get the current scheduling priority. | |
result_t | priority_inherited (priority_t prio) |
Set the inherited 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. | |
static const std::size_t | stack_size_bytes = N |
Local constant based on template definition. | |
Template of a POSIX compliant thread with local stack.
N | Size of statically allocated stack in bytes. |
Definition at line 1823 of file os-thread.h.
|
inherited |
Default RTOS allocator.
Definition at line 1014 of file os-thread.h.
|
inherited |
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.
|
inherited |
Type of thread function.
Useful to cast other similar types to silence possible compiler warnings.
Definition at line 420 of file os-thread.h.
|
inherited |
Type of variables holding thread states.
Definition at line 356 of file os-thread.h.
|
inline |
Construct a thread object instance.
[in] | function | Pointer to thread function. |
[in] | args | Pointer to thread function arguments. |
[in] | attr | Reference to attributes. |
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.
The storage shall be statically allocated inside the thread object instance.
Implemented as a wrapper over the parent constructor, automatically passing the stack size and address.
pthread_create()
from <pthread.h>
(IEEE Std 1003.1, 2013 Edition).Definition at line 2724 of file os-thread.h.
os::rtos::thread_inclusive< N >::thread_inclusive | ( | const char * | name, |
func_t | function, | ||
func_args_t | args, | ||
const attributes & | attr = initializer |
||
) |
Construct a named thread object instance.
[in] | name | Pointer to name. |
[in] | function | Pointer to thread function. |
[in] | args | Pointer to thread function arguments. |
[in] | attr | Reference to attributes. |
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.
The storage shall be statically allocated inside the thread object instance.
Implemented as a wrapper over the parent constructor, automatically passing the stack size and address.
pthread_create()
from <pthread.h>
(IEEE Std 1003.1, 2013 Edition).Definition at line 2778 of file os-thread.h.
|
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.
Definition at line 2802 of file os-thread.h.
|
inherited |
Cancel thread execution.
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.
pthread_cancel()
from <pthread.h>
(IEEE Std 1003.1, 2013 Edition).Definition at line 967 of file os-thread.cpp.
|
inherited |
Detach a thread.
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.
pthread_detach()
from <pthread.h>
(IEEE Std 1003.1, 2013 Edition).The detach()
function shall not return an error code of EINTR
.
Definition at line 861 of file os-thread.cpp.
|
inherited |
Raise thread event flags.
[in] | mask | The OR-ed flags to raise. |
[out] | oflags | Optional pointer where to store the previous flags; may be nullptr . |
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.
Definition at line 1281 of file os-thread.cpp.
|
inlineinherited |
Get the thread function arguments.
Definition at line 2358 of file os-thread.h.
|
inherited |
Set the interrupt flag, possibly interrupting the thread.
[in] | 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.
Definition at line 992 of file os-thread.cpp.
|
inlineinherited |
Check if interrupted.
true | The thread was interrupted. |
false | The thread was not interrupted. |
Definition at line 2367 of file os-thread.h.
|
staticinherited |
Check if the thread is constructed.
[in] | thread | Reference to thread object instance. |
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.
memset()
.Definition at line 293 of file os-thread.cpp.
|
inherited |
Wait for thread termination.
[in] | exit_ptr | Pointer to thread exit value. (Optional, may be nullptr). |
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.
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].
Definition at line 916 of file os-thread.cpp.
|
inherited |
Force thread termination.
result::ok | The tread was terminated. |
pthread_kill()
from <pthread.h>
(IEEE Std 1003.1, 2013 Edition).Definition at line 1199 of file os-thread.cpp.
|
inlineinherited |
Get object name.
All objects return a non-null string; anonymous objects return "-"
.
Definition at line 759 of file os-decls.h.
|
inlinestaticinherited |
Deallocate the dynamically allocated object instance. using the RTOS system allocator.
ptr | Pointer to object. |
bytes | Number of bytes to deallocate. |
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.
Definition at line 122 of file os-inlines.h.
|
inlinestaticinherited |
Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.
ptr | Pointer to array of objects. |
bytes | Number of bytes to deallocate. |
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.
Definition at line 143 of file os-inlines.h.
|
inlinestaticinherited |
Allocate space for a new object instance using the RTOS system allocator.
bytes | Number of bytes to allocate. |
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.
Definition at line 44 of file os-inlines.h.
|
inlinestaticinherited |
Emplace a new object instance.
bytes | Number of bytes to emplace. |
ptr | Pointer to location to emplace the 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.
Definition at line 81 of file os-inlines.h.
|
inlinestaticinherited |
Allocate space for an array of new object instances using the RTOS system allocator.
bytes | Number of bytes to allocate. |
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.
Definition at line 62 of file os-inlines.h.
|
inlinestaticinherited |
Emplace an array of new object instances.
bytes | Number of bytes to emplace. |
ptr | Pointer to location to emplace the object. |
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.
Definition at line 98 of file os-inlines.h.
|
inlineinherited |
Compare threads.
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.
|
inherited |
Set the assigned scheduling priority.
[in] | prio | New priority. |
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
.
pthread_setschedprio()
from <pthread.h>
(IEEE Std 1003.1, 2013 Edition).Definition at line 715 of file os-thread.cpp.
|
inherited |
Get the current scheduling priority.
Definition at line 661 of file os-thread.cpp.
|
inherited |
Set the inherited scheduling priority.
[in] | prio | New priority. |
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
.
Definition at line 783 of file os-thread.cpp.
|
inherited |
Get the inherited scheduling priority.
priority::none
.Definition at line 687 of file os-thread.cpp.
|
inherited |
Resume the thread.
Internal, used in the implementation of synchronisation objects.
Definition at line 612 of file os-thread.cpp.
|
inlineinherited |
Get the thread context stack.
Definition at line 2445 of file os-thread.h.
|
inlineinherited |
Get thread scheduler state.
Definition at line 2349 of file os-thread.h.
|
inlineinherited |
Definition at line 2456 of file os-thread.h.
|
inlineinherited |
Get the 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.
OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE
is defined.Definition at line 2392 of file os-thread.h.
|
inherited |
Definition at line 255 of file os-thread.h.
|
staticinherited |
Default thread initialiser.
This variable is used by the default constructor.
Definition at line 1007 of file os-thread.h.
|
static |
Local constant based on template definition.
Definition at line 1830 of file os-thread.h.