Template of a POSIX compliant thread with local stack. More...

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

Inheritance diagram for os::rtos::thread_inclusive< N >:

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.

Detailed Description

template<std::size_t N = port::stack::default_size_bytes>
class os::rtos::thread_inclusive< N >

Template Parameters

N	Size of statically allocated stack in bytes.

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

Member Typedef Documentation

◆ allocator_type

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

inherited

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

◆ func_args_t

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

inherited

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

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

◆ func_t

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

inherited

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

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

◆ state_t

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

inherited

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

Constructor & Destructor Documentation

◆ thread_inclusive() [1/2]

template<std::size_t N>

os::rtos::thread_inclusive< N >::thread_inclusive	(	func_t	function,
		func_args_t	args,
		const attributes &	attr = `initializer`
	)

inline

Parameters

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

Note: These objects are better instantiated as global static objects. When instantiated on the thread stack, the stack should be sized accordingly.

Implemented as a wrapper over the parent constructor, automatically passing the stack size and address.

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

        : thread_inclusive<N>{ nullptr, function, args, attr }
    {
    }

◆ thread_inclusive() [2/2]

template<std::size_t N>

os::rtos::thread_inclusive< N >::thread_inclusive	(	const char *	name,
		func_t	function,
		func_args_t	args,
		const attributes &	attr = `initializer`
	)

Parameters

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

Note: These objects are better instantiated as global static objects. When instantiated on the thread stack, the stack should be sized accordingly.

Implemented as a wrapper over the parent constructor, automatically passing the stack size and address.

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

        : thread{ name }
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s @%p %s\n", __func__, this, this->name ());
#endif
      internal_construct_ (function, args, attr, &stack_, stack_size_bytes);
    }

References os::trace::printf(), and os::rtos::thread_inclusive< N >::stack_size_bytes.

◆ ~thread_inclusive()

template<std::size_t N>

os::rtos::thread_inclusive< N >::~thread_inclusive

overridevirtual

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.

POSIX compatibility: No POSIX similar functionality identified.

Warning: Cannot be invoked from Interrupt Service Routines.

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s @%p %s\n", __func__, this, name ());
#endif
    }

References os::trace::printf().

Member Function Documentation

◆ cancel()

result_t thread::cancel ( void )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      // TODO: implement according to POSIX specs.
      return result::ok;
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, and os::trace::printf().

◆ detach()

result_t thread::detach ( void )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
      result_t res = port::thread::detach (this);
      if (res != result::ok)
        {
          return res;
        }
 
#else
 
      // TODO: implement
 
#endif
 
      return result::ok;
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, and os::trace::printf().

Referenced by thread::detach().

◆ flags_raise()

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

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X) @%p %s <0x%X\n", __func__, mask, this, name (),
                     event_flags_.mask ());
#endif
 
      result_t res = event_flags_.raise (mask, oflags);
 
      this->resume ();
 
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X) @%p %s >0x%X\n", __func__, mask, this, name (),
                     event_flags_.mask ());
#endif
 
      return res;
    }

References os::rtos::internal::object_named::name(), os::trace::printf(), and os::rtos::thread::resume().

◆ function_args()

void * thread::function_args ( void ) const

inlineinherited

Parameters: None.

Returns: Pointer to arguments.

Warning: Cannot be invoked from Interrupt Service Routines.

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

    {
      return func_args_;
    }

Referenced by thread::delete_system_thread().

◆ interrupt()

bool thread::interrupt ( bool interrupt = true )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      bool tmp = interrupted_;
      interrupted_ = interrupt;
 
      resume ();
      return tmp;
    }

References os::rtos::thread::interrupt(), os::rtos::internal::object_named::name(), os::trace::printf(), and os::rtos::thread::resume().

Referenced by os::rtos::thread::interrupt().

◆ interrupted()

bool thread::interrupted ( void )

inlineinherited

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

    {
      return interrupted_;
    }

Referenced by os::rtos::mutex::lock(), os::rtos::message_queue::receive(), os::rtos::message_queue::send(), 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::event_flags::wait(), and os::rtos::semaphore::wait().

◆ is_constructed()

bool thread::is_constructed ( const thread & thread )

staticinherited

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

    {
      return ((thread.state_ == state::ready || thread.state_ == state::running
               || thread.state_ == state::suspended
               || thread.state_ == state::terminated));
    }

References os::rtos::thread::state::ready, os::rtos::thread::state::running, os::rtos::thread::state::suspended, and os::rtos::thread::state::terminated.

Referenced by os_thread_is_constructed().

◆ join()

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

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_err (!scheduler::locked (), EPERM);
 
      // Fail if current thread
      assert (this != this_thread::_thread ());
 
      while (state_ != state::destroyed)
        {
          joiner_ = this_thread::_thread ();
          this_thread::_thread ()->internal_suspend_ ();
        }
 
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s joined\n", __func__, this, name ());
#endif
 
      if (exit_ptr != nullptr)
        {
          *exit_ptr = func_result_;
        }
 
      return result::ok;
    }

References os::rtos::thread::state::destroyed, os::rtos::interrupts::in_handler_mode(), os::rtos::scheduler::locked(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, and os::trace::printf().

Referenced by os_thread_join().

◆ kill()

result_t thread::kill ( void )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        if (state_ == state::destroyed)
          {
#if defined(OS_TRACE_RTOS_THREAD)
            trace::printf ("%s() @%p %s already gone\n", __func__, this,
                           name ());
#endif
            return result::ok; // Already exited itself
          }
 
        {
          // ----- Enter critical section -------------------------------------
          interrupts::critical_section ics;
 
          // Remove thread from the funeral list and kill it here.
          ready_node_.unlink ();
 
          // If the thread is waiting on an event, remove it from the list.
          if (waiting_node_ != nullptr)
            {
              waiting_node_->unlink ();
            }
 
          // If the thread is waiting on a timeout, remove it from the list.
          if (clock_node_ != nullptr)
            {
              clock_node_->unlink ();
            }
 
          child_links_.unlink ();
          // ----- Exit critical section --------------------------------------
        }
 
        // The must be no more children threads alive.
        assert (children_.empty ());
        parent_ = nullptr;
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
        port::thread::destroy_other (this);
 
#endif
 
        func_result_ = nullptr;
 
        func_ = nullptr;
        func_args_ = nullptr;
 
        internal_destroy_ ();
 
        // There must be no mutexes locked by this thread.
        // Must have been cleaned before.
        assert (mutexes_.empty ());
        assert (acquired_mutexes_ == 0);
 
        // ----- Exit critical section ----------------------------------------
      }
 
      return result::ok;
    }

References os::rtos::thread::state::destroyed, os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, and os::trace::printf().

Referenced by os::rtos::thread::~thread(), and os_thread_kill().

◆ name()

const char * os::rtos::internal::object_named::name ( void ) const

inlineinherited

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 753 of file os-decls.h.

      {
        return name_;
      }

◆ operator delete()

void os::rtos::internal::object_named_system::operator delete	(	void *	ptr,
		std::size_t	bytes
	)

inlinestaticinherited

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 120 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        rtos::memory::allocator<char> ().deallocate (static_cast<char*> (ptr),
                                                     bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::deallocate(), and os::rtos::interrupts::in_handler_mode().

◆ operator delete[]()

void os::rtos::internal::object_named_system::operator delete[]	(	void *	ptr,
		std::size_t	bytes
	)

inlinestaticinherited

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 141 of file os-inlines.h.

      {
        // Forward array deallocation to single element deallocation.
        operator delete (ptr, bytes);
      }

◆ operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t bytes )

inlinestaticinherited

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 43 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        return rtos::memory::allocator<char> ().allocate (bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::allocate(), and os::rtos::interrupts::in_handler_mode().

◆ operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new	(	std::size_t	bytes,
		void *	ptr
	)

inlinestaticinherited

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 80 of file os-inlines.h.

      {
        return ptr;
      }

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

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t bytes )

inlinestaticinherited

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 61 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes);
      }

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

void * os::rtos::internal::object_named_system::operator new[]	(	std::size_t	bytes,
		void *	ptr
	)

inlinestaticinherited

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 97 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes, ptr);
      }

◆ operator==()

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

inlineinherited

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

    {
      return this == &rhs;
    }

◆ priority() [1/2]

result_t thread::priority ( priority_t prio )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s(%u) @%p %s\n", __func__, prio, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Check the priority, it is not in the allowed range.
      os_assert_err (prio < priority::error, EINVAL);
      os_assert_err (prio != priority::none, EINVAL);
 
      if (prio_assigned_ == prio)
        {
          // Optimise, if priority did not change.
          return result::ok;
        }
 
      prio_assigned_ = prio;
 
      result_t res = result::ok;
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
      // The port must perform a context switch.
      res = port::thread::priority (this, prio);
 
#else
 
      if (state_ == state::ready)
        {
          // ----- Enter critical section -------------------------------------
          interrupts::critical_section ics;
 
          // Remove from initial location and reinsert according
          // to new priority.
          ready_node_.unlink ();
          scheduler::ready_threads_list_.link (ready_node_);
          // ----- Exit critical section --------------------------------------
        }
 
      // Mandatory, the priority might have been raised, the
      // task must be scheduled to run.
      this_thread::yield ();
 
#endif
 
      return res;
    }

References os::rtos::thread::priority::error, os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::thread::priority::none, os::rtos::result::ok, os_assert_err, os::trace::printf(), os::rtos::thread::state::ready, and os::rtos::this_thread::yield().

Referenced by os::rtos::internal::ready_threads_list::link(), and os::rtos::internal::waiting_threads_list::link().

◆ priority() [2/2]

thread::priority_t thread::priority ( void )

inherited

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

    {
      // trace::printf ("%s() @%p %s\n", __func__, this, name ());
 
      if (prio_inherited_ == priority::none)
        {
          // The common case is to have no inherited priority;
          // return the assigned one.
          return prio_assigned_;
        }
      else
        {
          // Return the maximum between inherited and assigned.
          return (prio_inherited_ >= prio_assigned_) ? prio_inherited_
                                                     : prio_assigned_;
        }
    }

References os::rtos::thread::priority::none.

◆ priority_inherited() [1/2]

result_t thread::priority_inherited ( priority_t prio )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s(%u) @%p %s\n", __func__, prio, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Check the priority, it is not in the allowed range.
      os_assert_err (prio < priority::error, EINVAL);
 
      // Warning: do not check for `priority::none`, since
      // `mutex::unlock()` sets it when the list of mutexes owned
      // by a thread is empty.
 
      if (prio == prio_inherited_)
        {
          // Optimise, if priority did not change.
          return result::ok;
        }
 
      prio_inherited_ = prio;
 
      if (prio_inherited_ < prio_assigned_)
        {
          // Optimise, no need to reschedule.
          return result::ok;
        }
 
      result_t res = result::ok;
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
      // The port must perform a context switch.
      res = port::thread::priority (this, prio);
 
#else
 
      if (state_ == state::ready)
        {
          // ----- Enter critical section -------------------------------------
          interrupts::critical_section ics;
 
          // Remove from initial location and reinsert according
          // to new priority.
          ready_node_.unlink ();
          scheduler::ready_threads_list_.link (ready_node_);
          // ----- Exit critical section --------------------------------------
        }
 
      // Mandatory, the priority might have been raised, the
      // task must be scheduled to run.
      this_thread::yield ();
 
#endif
 
      return res;
    }

References os::rtos::thread::priority::error, os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, os::trace::printf(), os::rtos::thread::state::ready, and os::rtos::this_thread::yield().

◆ priority_inherited() [2/2]

thread::priority_t thread::priority_inherited ( void )

inherited

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

    {
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), priority::error);
 
      return prio_inherited_;
    }

References os::rtos::thread::priority::error, os::rtos::interrupts::in_handler_mode(), and os_assert_err.

◆ resume()

void thread::resume ( void )

inherited

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

    {
#if defined(OS_TRACE_RTOS_THREAD_CONTEXT)
      trace::printf ("%s() @%p %s %u\n", __func__, this, name (),
                     prio_assigned_);
#endif
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        state_ = state::ready;
        port::thread::resume (this);
        // ----- Exit critical section ----------------------------------------
      }
 
#else
 
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        // If the thread is not already in the ready list, enqueue it.
        if (ready_node_.next () == nullptr)
          {
            scheduler::ready_threads_list_.link (ready_node_);
            // state::ready set in above link().
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      port::scheduler::reschedule ();
 
#endif
    }

References os::rtos::internal::object_named::name(), os::trace::printf(), os::rtos::thread::state::ready, and os::rtos::port::scheduler::reschedule().

Referenced by os::rtos::internal::timeout_thread_node::action(), os::rtos::thread::flags_raise(), os::rtos::thread::interrupt(), and os::rtos::internal::waiting_threads_list::resume_one().

◆ stack()

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

inlineinherited

Parameters: None.

Returns: A reference to the context stack object instance.

Note: Can be invoked from Interrupt Service Routines.

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

    {
      return context_.stack_;
    }

Referenced by os_terminate_goodbye().

◆ state()

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

inlineinherited

Parameters: None.

Returns: Thread scheduler state.

Note: Can be invoked from Interrupt Service Routines.

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

    {
      return state_;
    }

Referenced by os::rtos::internal::timeout_thread_node::action(), and os::rtos::internal::waiting_threads_list::resume_one().

◆ statistics()

class thread::statistics & thread::statistics ( void )

inlineinherited

Warning: Cannot be invoked from Interrupt Service Routines.

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

    {
      return statistics_;
    }

◆ user_storage()

os_thread_user_storage_t * thread::user_storage ( void )

inlineinherited

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

    {
      return &user_storage_;
    }

Member Data Documentation

◆ errno_

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

inherited

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

Referenced by os::rtos::this_thread::__errno().

◆ initializer

const thread::attributes thread::initializer

staticinherited

This variable is used by the default constructor.

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

◆ stack_size_bytes

template<std::size_t N = port::stack::default_size_bytes>

const std::size_t os::rtos::thread_inclusive< N >::stack_size_bytes = N

static

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

Referenced by os::rtos::thread_inclusive< N >::thread_inclusive().

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

os-thread.h

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_inclusive() [1/2]

◆ thread_inclusive() [2/2]

◆ ~thread_inclusive()

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

◆ stack_size_bytes