µOS++ IIIe / CMSIS++ / POSIX++ Reference  v6.3.11
“Perfekt ist nicht gut genug”
The third edition of µOS++ and CMSIS++, a proposal for the next generation CMSIS, written in C++.
os::rtos::this_thread Namespace Reference

A convenience namespace to access the current running thread. More...

Functions

int * __errno (void)
 Implementation of the library __errno() function. More...
 
void exit (void *exit_ptr=nullptr)
 Terminate the current running thread. More...
 
result_t flags_clear (flags::mask_t mask, flags::mask_t *oflags=nullptr)
 Clear thread event flags. More...
 
flags::mask_t flags_get (flags::mask_t mask, flags::mode_t mode=flags::mode::all|flags::mode::clear)
 Get/clear thread event flags. More...
 
result_t flags_timed_wait (flags::mask_t mask, clock::duration_t timeout, flags::mask_t *oflags=nullptr, flags::mode_t mode=flags::mode::all|flags::mode::clear)
 Timed wait for thread event flags. More...
 
result_t flags_try_wait (flags::mask_t mask, flags::mask_t *oflags=nullptr, flags::mode_t mode=flags::mode::all|flags::mode::clear)
 Try to wait for thread event flags. More...
 
result_t flags_wait (flags::mask_t mask, flags::mask_t *oflags=nullptr, flags::mode_t mode=flags::mode::all|flags::mode::clear)
 Wait for thread event flags. More...
 
void suspend (void)
 Suspend the current running thread to wait for an event. More...
 
threadthread (void)
 Get the current running thread. More...
 
void yield (void)
 Yield execution to the next ready thread. More...
 

Detailed Description

A convenience namespace to access the current running thread.

The os::rtos::this_thread namespace groups functions related to the current thread.

Function Documentation

int * os::rtos::this_thread::__errno ( void  )
inline

Implementation of the library __errno() function.

Returns
Pointer to thread specific errno.

The actual C library function, used by newlib, is in os-core.cpp.

See also
__errno()

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

void os::rtos::this_thread::exit ( void *  exit_ptr = nullptr)
inline

Terminate the current running thread.

Parameters
[in]exit_ptrPointer to object to return. (Optional, may be nullptr).
Returns
Nothing.

Terminate the calling thread and make the value value_ptr available to any successful join with the terminating thread. Any cancellation cleanup handlers that have been pushed and not yet popped shall be popped in the reverse order that they were pushed and then executed. After all cancellation cleanup handlers have been executed, if the thread has any thread-specific data, appropriate destructor functions shall be called in an unspecified order. Thread termination does not release any application visible process resources, including, but not limited to, mutexes and file descriptors, nor does it perform any process-level cleanup actions, including, but not limited to, calling any atexit() routines that may exist. An implicit call to exit() is made when a thread other than the thread in which main() was first invoked returns from the start routine that was used to create it. The function's return value shall serve as the thread's exit code. The behaviour of internal_exit_() is undefined if called from a cancellation cleanup handler or destructor function that was invoked as a result of either an implicit or explicit call to exit(). After a thread has terminated, the result of access to local (auto) variables of the thread is undefined. Thus, references to local variables of the exiting thread should not be used for the exit() value_ptr parameter value.

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

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

result_t os::rtos::this_thread::flags_clear ( flags::mask_t  mask,
flags::mask_t oflags = nullptr 
)
inline

Clear thread event flags.

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

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

flags::mask_t os::rtos::this_thread::flags_get ( flags::mask_t  mask,
flags::mode_t  mode = flags::mode::all | flags::mode::clear 
)
inline

Get/clear thread event flags.

Parameters
[in]maskThe OR-ed flags to get/clear; may be zero.
[in]modeMode bits to select if the flags should be cleared (the other bits are ignored).
Return values
flagsThe selected bits from the current thread event flags mask.
flags::allCannot be invoked from an Interrupt Service Routines.

Select the requested bits from the thread current flags mask and return them. If requested, clear the selected bits in the thread flags mask.

If the mask is zero, return the full thread flags mask, without any masking or subsequent clearing.

Warning
Cannot be invoked from Interrupt Service Routines.

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

result_t os::rtos::this_thread::flags_timed_wait ( flags::mask_t  mask,
clock::duration_t  timeout,
flags::mask_t oflags = nullptr,
flags::mode_t  mode = flags::mode::all | flags::mode::clear 
)
inline

Timed wait for thread event flags.

Parameters
[in]maskThe expected flags (OR-ed bit-mask); may be zero.
[out]oflagsPointer where to store the current flags; may be nullptr.
[in]modeMode bits to select if either all or any flags are expected, and if the flags should be cleared.
[in]timeoutTimeout to wait, in clock units (ticks or seconds).
Return values
result::okAll expected flags are raised.
EPERMCannot be invoked from an Interrupt Service Routines.
ETIMEDOUTThe expected condition did not occur during the entire timeout duration.
EINVALThe mask is outside of the permitted range.
EINTRThe operation was interrupted.
ENOTRECOVERABLEWait failed.

If the flags::mode::all bit is set, the function expects all given flags to be raised; otherwise, if the flags::mode::any bit is set, the function expects any single flag to be raised.

If the expected event flags are raised, the function returns instantly.

Otherwise suspend the execution of the thread until all/any specified event flags are raised.

When the parameter mask is 0, the thread is suspended until any event flag is raised. In this case, if any event flags are already raised, the function returns instantly.

The wait shall be terminated when the specified timeout expires.

The timeout shall expire after the number of time units (that is when the value of that clock equals or exceeds (now()+duration). The resolution of the timeout shall be the resolution of the clock on which it is based (the SysTick clock for CMSIS).

Under no circumstance shall the operation fail with a timeout if the event flags are already raised. The validity of the timeout need not be checked if the expected flags are already raised and the call can return immediately.

The clock used for timeouts can be specified via the clock attribute. By default, the clock derived from the scheduler timer is used, and the durations are expressed in ticks.

If the flags::mode::clear bit is set, the event flags that are returned are automatically cleared.

Warning
Cannot be invoked from Interrupt Service Routines.

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

result_t os::rtos::this_thread::flags_try_wait ( flags::mask_t  mask,
flags::mask_t oflags = nullptr,
flags::mode_t  mode = flags::mode::all | flags::mode::clear 
)
inline

Try to wait for thread event flags.

Parameters
[in]maskThe expected flags (OR-ed bit-mask); may be zero.
[out]oflagsPointer where to store the current flags; may be nullptr.
[in]modeMode bits to select if either all or any flags are expected, and if the flags should be cleared.
Return values
result::okAll expected flags are raised.
EINVALThe mask is outside of the permitted range.
EWOULDBLOCKThe expected condition did not occur.
ENOTRECOVERABLEWait failed.

If the flags::mode::all bit is set, the function expects all given flags to be raised; otherwise, if the flags::mode::any bit is set, the function expects any single flag to be raised.

The function does not blocks, if the expected event flags are not raised, but returns EGAIN.

Warning
Cannot be invoked from Interrupt Service Routines.

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

result_t os::rtos::this_thread::flags_wait ( flags::mask_t  mask,
flags::mask_t oflags = nullptr,
flags::mode_t  mode = flags::mode::all | flags::mode::clear 
)
inline

Wait for thread event flags.

Parameters
[in]maskThe expected flags (OR-ed bit-mask); may be zero.
[out]oflagsPointer where to store the current flags; may be nullptr.
[in]modeMode bits to select if either all or any flags are expected, and if the flags should be cleared.
Return values
result::okAll expected flags are raised.
EPERMCannot be invoked from an Interrupt Service Routines.
EINVALThe mask is outside of the permitted range.
EINTRThe operation was interrupted.
ENOTRECOVERABLEWait failed.

If the flags::mode::all bit is set, the function expects all given flags to be raised; otherwise, if the flags::mode::any bit is set, the function expects any single flag to be raised.

If the expected event flags are raised, the function returns instantly.

Otherwise suspend the execution of the current thread until all/any specified event flags are raised.

When the parameter mask is 0, the thread is suspended until any event flag is raised. In this case, if any event flags are already raised, the function returns instantly.

If the flags::mode::clear bit is set, the event flags that are returned are automatically cleared.

Warning
Cannot be invoked from Interrupt Service Routines.

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

void os::rtos::this_thread::suspend ( void  )
inline

Suspend the current running thread to wait for an event.

Parameters
None.
Returns
Nothing.

Remove the current running thread from the ready list and pass control to the next ready thread. The thread will not be automatically rescheduled, it requires some other tread or interrupt service routine to add it back to the READY state (via thread::resume()).

This is different from yield() which automatically reschedules the current thread before passing control to the next thread (which might be the same if no other threads with at least the same priority are ready).

Warning
Cannot be invoked from Interrupt Service Routines.

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

rtos::thread & os::rtos::this_thread::thread ( void  )

Get the current running thread.

Parameters
None.
Returns
Reference to the current running thread.
Warning
Cannot be invoked from Interrupt Service Routines.

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

void os::rtos::this_thread::yield ( void  )

Yield execution to the next ready thread.

Parameters
None.
Returns
Nothing.

Pass control to next thread that is in READY state.

Warning
Cannot be invoked from Interrupt Service Routines.

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