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

Functions
int *	__errno (void)
	Implementation of the library `__errno()` function.

void	exit (void *exit_ptr=nullptr)
	Terminate the current running thread.

result_t	flags_clear (flags::mask_t mask, flags::mask_t *oflags=nullptr)
	Clear thread event flags.

flags::mask_t	flags_get (flags::mask_t mask, flags::mode_t mode=flags::mode::all\|flags::mode::clear)
	Get/clear thread event flags.

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.

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.

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.

void	suspend (void)
	Suspend the current running thread to wait for an event.

thread &	thread (void)
	Get the current running thread.

void	yield (void)
	Yield execution to the next ready thread.

Detailed Description

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

Function Documentation

◆ __errno()

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

inline

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

      {
        return &this_thread::thread ().errno_;
      }

References os::rtos::thread::errno_, and thread().

Referenced by __errno().

◆ exit()

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

inline

Parameters

[in] exit_ptr Pointer 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 2092 of file os-thread.h.

      {
        this_thread::thread ().internal_exit_ (exit_ptr);
      }

References thread().

◆ flags_clear()

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

inline

Parameters

[in]	mask	The OR-ed flags to clear.
[out]	oflags	Optional pointer where to store the previous flags; may be `nullptr`.

Return values

result::ok	The flags were cleared.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The mask is zero.

Warning: Cannot be invoked from Interrupt Service Routines.

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

      {
        return this_thread::thread ().internal_flags_clear_ (mask, oflags);
      }

References thread().

◆ flags_get()

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

inline

Parameters

[in]	mask	The OR-ed flags to get/clear; may be zero.
[in]	mode	Mode bits to select if the flags should be cleared (the other bits are ignored).

Return values

flags	The selected bits from the current thread event flags mask.
flags::all	Cannot 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 2037 of file os-thread.h.

      {
        return this_thread::thread ().internal_flags_get_ (mask, mode);
      }

References thread().

◆ flags_timed_wait()

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

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be `nullptr`.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.
[in]	timeout	Timeout to wait, in clock units (ticks or seconds).

Return values

result::ok	All expected flags are raised.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The expected condition did not occur during the entire timeout duration.
EINVAL	The mask is outside of the permitted range.
EINTR	The operation was interrupted.
ENOTRECOVERABLE	Wait 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 2018 of file os-thread.h.

      {
        return this_thread::thread ().internal_flags_timed_wait_ (
            mask, timeout, oflags, mode);
      }

References thread().

◆ flags_try_wait()

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

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be `nullptr`.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.

Return values

result::ok	All expected flags are raised.
EINVAL	The mask is outside of the permitted range.
EWOULDBLOCK	The expected condition did not occur.
ENOTRECOVERABLE	Wait 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 1972 of file os-thread.h.

      {
        return this_thread::thread ().internal_flags_try_wait_ (mask, oflags,
                                                                mode);
      }

References thread().

◆ flags_wait()

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

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be `nullptr`.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.

Return values

result::ok	All expected flags are raised.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The mask is outside of the permitted range.
EINTR	The operation was interrupted.
ENOTRECOVERABLE	Wait 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 1953 of file os-thread.h.

      {
        return this_thread::thread ().internal_flags_wait_ (mask, oflags,
                                                            mode);
      }

References thread().

◆ suspend()

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

inline

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

      {
        this_thread::thread ().internal_suspend_ ();
      }

References thread().

◆ thread()

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

Parameters: None.

Returns: Reference to the current running thread.

Warning: Cannot be invoked from Interrupt Service Routines.

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

      {
        // Don't call this from interrupt handlers.
        os_assert_throw (!interrupts::in_handler_mode (), EPERM);
 
        rtos::thread* th;
 
        th = _thread ();
 
        // Could not get the current thread.
        assert (th != nullptr);
        return (*th);
      }

References os::rtos::interrupts::in_handler_mode(), and os_assert_throw.

Referenced by os::rtos::thread::~thread(), __errno(), os::rtos::memory_pool::alloc(), exit(), flags_clear(), flags_get(), flags_timed_wait(), flags_try_wait(), flags_wait(), os::rtos::mutex::lock(), os::rtos::message_queue::receive(), os::rtos::message_queue::send(), os::rtos::clock::sleep_for(), os::rtos::clock::sleep_until(), suspend(), os::rtos::memory_pool::timed_alloc(), os::rtos::mutex::timed_lock(), os::rtos::message_queue::timed_receive(), os::rtos::message_queue::timed_send(), os::rtos::semaphore::timed_wait(), os::rtos::event_flags::timed_wait(), os::rtos::mutex::try_lock(), os::rtos::mutex::unlock(), os::rtos::event_flags::wait(), os::rtos::semaphore::wait(), and os::rtos::clock::wait_for().

◆ yield()

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

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

      {
        // Don't call this from interrupt handlers.
        os_assert_throw (!interrupts::in_handler_mode (), EPERM);
 
        if (!scheduler::started ())
          {
#if defined(OS_TRACE_RTOS_THREAD_CONTEXT)
            trace::printf ("%s() nop %s \n", __func__, _thread ()->name ());
#endif
            return;
          }
 
#if defined(OS_TRACE_RTOS_THREAD_CONTEXT)
        trace::printf ("%s() from %s\n", __func__, _thread ()->name ());
#endif
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
        port::this_thread::yield ();
 
#else
 
        port::scheduler::reschedule ();
 
#endif
 
#if defined(OS_TRACE_RTOS_THREAD_CONTEXT)
        trace::printf ("%s() to %s\n", __func__, _thread ()->name ());
#endif
      }

References os::rtos::interrupts::in_handler_mode(), os_assert_throw, os::trace::printf(), os::rtos::port::scheduler::reschedule(), os::rtos::scheduler::started(), and os::rtos::port::this_thread::yield().

Referenced by os::rtos::thread::priority(), and os::rtos::thread::priority_inherited().

Functions

Detailed Description

Function Documentation

◆ __errno()

◆ exit()

◆ flags_clear()

◆ flags_get()

◆ flags_timed_wait()

◆ flags_try_wait()

◆ flags_wait()

◆ suspend()

◆ thread()

◆ yield()