os-thread.cpp

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2016-2025 Liviu Ionescu. All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software
 * for any purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can
 * be obtained from https://opensource.org/licenses/mit.
 */
 
#if defined(OS_USE_OS_APP_CONFIG_H)
#include <cmsis-plus/os-app-config.h>
#endif
 
#include <cmsis-plus/rtos/os.h>
 
#include <memory>
#include <stdexcept>
 
// ----------------------------------------------------------------------------
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#endif
 
// ----------------------------------------------------------------------------
 
namespace os
{
  namespace rtos
  {
    // ------------------------------------------------------------------------
 
    std::size_t thread::stack::min_size_bytes_ = port::stack::min_size_bytes;
 
    std::size_t thread::stack::default_size_bytes_
        = port::stack::default_size_bytes;
 
    // ------------------------------------------------------------------------
    using mutexes_list = utils::intrusive_list<mutex, utils::double_list_links,
                                               &mutex::owner_links_>;
 
    // ========================================================================
    const thread::attributes thread::initializer;
 
    void
    thread::stack::initialize (void)
    {
      // Align the bottom of the stack.
      void* pa = bottom_address_;
      bottom_address_ = static_cast<stack::element_t*> (
          std::align (sizeof (stack::allocation_element_t), stack::min_size (),
                      pa, size_bytes_));
 
      // If there is not enough space for the minimal stack, fail.
      os_assert_throw (bottom_address_ != nullptr, ENOMEM);
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
#endif
      element_t* p = bottom_address_;
      element_t* pend = top ();
 
      // Initialise the entire stack with the magic word.
      for (; p < pend; ++p)
        {
          *p = magic;
        }
#pragma GCC diagnostic pop
 
      // Compute the actual size. The -1 is to leave space for the magic.
      size_bytes_ = ((static_cast<std::size_t> (p - bottom_address_) - 1)
                     * sizeof (element_t));
    }
 
    std::size_t
    thread::stack::available (void)
    {
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
#endif
      element_t* p = bottom_address_;
      std::size_t count = 0;
      while (*p == magic)
        {
          count += sizeof (element_t);
          ++p;
        }
#pragma GCC diagnostic pop
 
      return count;
    }
 
    void
    thread::internal_invoke_with_exit_ (thread* thread)
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, thread, thread->name ());
#endif
 
      void* exit_ptr;
#if defined(__EXCEPTIONS)
      try
        {
          exit_ptr = thread->func_ (thread->func_args_);
        }
      catch (std::exception const& e)
        {
          trace::printf ("%s() @%p %s top exception \"%s\"\n", __func__,
                         thread, thread->name (), e.what ());
          exit_ptr = nullptr;
        }
      catch (...)
        {
          trace::printf ("%s() @%p %s top exception\n", __func__, thread,
                         thread->name ());
          exit_ptr = nullptr;
        }
#else
      exit_ptr = thread->func_ (thread->func_args_);
#endif
      thread->internal_exit_ (exit_ptr);
    }
 
    thread::thread ()
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, this->name ());
#endif
      // Must be explicit here, since they are not done in the members
      // declarations to allow th_enable_assert_reuse.
      state_ = state::initializing;
      func_ = nullptr;
    }
 
    thread::thread (const char* name) : object_named_system{ name }
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, this->name ());
#endif
      // Must be explicit here, since they are not done in the members
      // declarations to allow th_enable_assert_reuse.
      state_ = state::initializing;
    }
 
    bool
    thread::is_constructed (const thread& thread)
    {
      return ((thread.state_ == state::ready || thread.state_ == state::running
               || thread.state_ == state::suspended
               || thread.state_ == state::terminated));
    }
 
    thread::thread (func_t function, func_args_t args, const attributes& attr,
                    const allocator_type& allocator)
        : thread{ nullptr, function, args, attr, allocator }
    {
    }
 
    thread::thread (const char* name, func_t function, func_args_t args,
                    const attributes& attr, const allocator_type& allocator)
        : object_named_system{ name }
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, this->name ());
#endif
 
#if defined(DEBUG)
      if (attr.th_enable_assert_reuse)
        {
          // Expect either statically initialised (undefined), or destroyed.
          assert ((state_ == state::undefined)
                  || (state_ == state::destroyed));
        }
#endif /* DEBUG */
 
      state_ = state::initializing;
 
      allocator_ = &allocator;
 
      if (attr.th_stack_address != nullptr
          && attr.th_stack_size_bytes > stack::min_size ())
        {
          internal_construct_ (function, args, attr, nullptr, 0);
        }
      else
        {
          using allocator_type2
              = memory::allocator<stack::allocation_element_t>;
 
          if (attr.th_stack_size_bytes > stack::min_size ())
            {
              allocated_stack_size_elements_
                  = (attr.th_stack_size_bytes
                     + sizeof (stack::allocation_element_t) - 1)
                    / sizeof (stack::allocation_element_t);
            }
          else
            {
              allocated_stack_size_elements_
                  = (stack::default_size ()
                     + sizeof (stack::allocation_element_t) - 1)
                    / sizeof (stack::allocation_element_t);
            }
 
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
          allocated_stack_address_ = reinterpret_cast<stack::element_t*> (
              const_cast<allocator_type2&> (allocator).allocate (
                  allocated_stack_size_elements_));
#pragma GCC diagnostic pop
 
          // Stack allocation failed.
          assert (allocated_stack_address_ != nullptr);
 
          internal_construct_ (function, args, attr, allocated_stack_address_,
                               allocated_stack_size_elements_
                                   * sizeof (stack::allocation_element_t));
        }
    }
 
    void
    thread::internal_construct_ (func_t function, func_args_t args,
                                 const attributes& attr, void* stack_address,
                                 std::size_t stack_size_bytes)
    {
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
 
      // The thread function must be real.
      assert (function != nullptr);
      // Don't forget to set the thread priority.
      assert (attr.th_priority != priority::none);
 
      clock_ = attr.clock != nullptr ? attr.clock : &sysclock;
 
      if (stack_address != nullptr)
        {
          // The attributes should not define any storage in this case.
          if (attr.th_stack_size_bytes > stack::min_size ())
            {
              // The stack address must be real.
              assert (attr.th_stack_address == nullptr);
            }
 
          stack ().set (static_cast<stack::element_t*> (stack_address),
                        stack_size_bytes);
        }
      else
        {
          stack ().set (static_cast<stack::element_t*> (attr.th_stack_address),
                        attr.th_stack_size_bytes);
        }
 
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s p%u stack{%p,%u}\n", __func__, this, name (),
                     attr.th_priority, stack ().bottom_address_,
                     stack ().size_bytes_);
#endif
 
      {
        // Prevent the new thread to execute before all members are set.
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        // Get attributes from user structure.
        prio_assigned_ = attr.th_priority;
 
        func_ = function;
        func_args_ = args;
 
        parent_ = this_thread::_thread ();
        if (scheduler::started () && (parent_ != nullptr))
          {
            parent_->children_.link (*this);
          }
        else
          {
            scheduler::top_threads_list_.link (*this);
          }
 
        stack ().initialize ();
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
        port::thread::create (this);
        state_ = state::ready;
 
#else
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
#endif
        // Create the port specific context.
        port::context::create (
            &context_, reinterpret_cast<void*> (internal_invoke_with_exit_),
            this);
#pragma GCC diagnostic pop
 
        if (!scheduler::started ())
          {
            scheduler::current_thread_ = this;
          }
 
        // Add to ready list, but do not yield yet.
        resume ();
 
#endif
        // ----- Exit critical section ----------------------------------------
      }
      // For just in case the new thread has higher priority.
      this_thread::yield ();
    }
 
    thread::~thread ()
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s \n", __func__, this, name ());
#endif
 
      // Prevent the main thread to destroy itself while running
      // the exit cleanup code.
      if (this != &this_thread::thread ())
        {
          // Extra test to avoid the 'already gone' message.
          if (state_ != state::destroyed)
            {
              kill ();
            }
        }
      else
        {
#if defined(OS_TRACE_RTOS_THREAD)
          trace::printf ("%s() @%p %s nop, cannot commit suicide\n", __func__,
                         this, name ());
#endif
        }
    }
 
    void
    thread::resume (void)
    {
#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
    }
 
    thread::priority_t
    thread::priority (void)
    {
      // 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_;
        }
    }
 
    thread::priority_t
    thread::priority_inherited (void)
    {
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), priority::error);
 
      return prio_inherited_;
    }
 
    result_t
    thread::priority (priority_t prio)
    {
#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;
    }
 
    result_t
    thread::priority_inherited (priority_t prio)
    {
#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;
    }
 
    result_t
    thread::detach (void)
    {
#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;
    }
 
    result_t
    thread::join (void** exit_ptr)
    {
#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;
    }
 
    result_t
    thread::cancel (void)
    {
#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;
    }
 
    bool
    thread::interrupt (bool interrupt)
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      bool tmp = interrupted_;
      interrupted_ = interrupt;
 
      resume ();
      return tmp;
    }
 
    void
    thread::internal_suspend_ (void)
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        // Remove this thread from the ready list, if there.
        port::this_thread::prepare_suspend ();
 
        state_ = state::suspended;
        // ----- Exit critical section ----------------------------------------
      }
 
      port::scheduler::reschedule ();
    }
 
    void
    thread::internal_exit_ (void* exit_ptr)
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      assert (!interrupts::in_handler_mode ());
 
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        {
          // ----- Enter critical section -------------------------------------
          interrupts::critical_section ics;
 
          ready_node_.unlink ();
 
          child_links_.unlink ();
          // ----- Exit critical section --------------------------------------
        }
 
        // There must be no children threads still alive.
        assert (children_.empty ());
        parent_ = nullptr;
 
        func_ = nullptr;
        func_args_ = nullptr;
 
        // There must be no more mutexes locked by this thread.
        assert (mutexes_.empty ());
        assert (acquired_mutexes_ == 0);
 
        func_result_ = exit_ptr;
        // ----- Exit critical section ----------------------------------------
      }
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        // Add to a list of threads to be destroyed by the idle thread.
        // Also set state::terminated.
        scheduler::terminated_threads_list_.link (ready_node_);
        // ----- Exit critical section ----------------------------------------
      }
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
      port::thread::destroy_this (this);
      // Does not return if the current thread.
 
#else
 
      // At this point, since the thread state is no longer 'running',
      // the thread is no longer linked in the READY list.
      port::scheduler::reschedule ();
 
#endif
 
      assert (true);
      while (true)
        ;
 
      // Definitely does not return.
    }
 
    void
    thread::internal_check_stack_ (void)
    {
      if (stack ().size () > 0)
        {
          if (!stack ().check_bottom_magic () || !stack ().check_top_magic ())
            {
              trace::printf ("%s() @%p %s\n", __func__, this, name ());
              assert (stack ().check_bottom_magic ());
              assert (stack ().check_top_magic ());
            }
 
#if defined(OS_TRACE_RTOS_THREAD)
          trace::printf (
              "%s() @%p %s stack: %u/%u bytes used\n", __func__, this, name (),
              stack ().size () - stack ().available (), stack ().size ());
#endif
 
          // Clear stack to avoid further checks
          stack ().clear ();
        }
    }
 
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wsuggest-final-methods"
#endif
    // Called from kill() and from idle thread.
    void
    thread::internal_destroy_ (void)
    {
#if defined(OS_TRACE_RTOS_THREAD)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      internal_check_stack_ ();
 
      if (allocated_stack_address_ != nullptr)
        {
          typedef
              typename std::allocator_traits<allocator_type>::pointer pointer;
 
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#pragma GCC diagnostic ignored "-Wcast-align"
#endif
          static_cast<allocator_type*> (const_cast<void*> (allocator_))
              ->deallocate (
                  reinterpret_cast<pointer> (allocated_stack_address_),
                  allocated_stack_size_elements_);
#pragma GCC diagnostic pop
 
          allocated_stack_address_ = nullptr;
        }
 
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        mutexes_list& mx_list = reinterpret_cast<mutexes_list&> (mutexes_);
        while (not mx_list.empty ())
          {
            auto* mx = mx_list.unlink_head ();
 
            mx->internal_mark_owner_dead_ ();
 
            // Unlock the mutex as owned by the thread itself.
            mx->internal_unlock_ (this);
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      state_ = state::destroyed;
 
      if (joiner_ != nullptr)
        {
          joiner_->resume ();
        }
    }
#pragma GCC diagnostic pop
 
    result_t
    thread::kill (void)
    {
#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;
    }
 
    result_t
    thread::flags_raise (flags::mask_t mask, flags::mask_t* oflags)
    {
#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;
    }
 
    result_t
    thread::internal_flags_wait_ (flags::mask_t mask, flags::mask_t* oflags,
                                  flags::mode_t mode)
    {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X,%u) @%p %s <0x%X\n", __func__, mask, mode, this,
                     name (), event_flags_.mask ());
#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);
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (event_flags_.check_raised (mask, oflags, mode))
          {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
            trace::printf ("%s(0x%X,%u) @%p %s >0x%X\n", __func__, mask, mode,
                           this, name (), event_flags_.mask ());
#endif
            return result::ok;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      clock::timestamp_t begin_timestamp = clock_->now ();
#endif
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            if (event_flags_.check_raised (mask, oflags, mode))
              {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
                clock::duration_t slept_ticks
                    = static_cast<clock::duration_t> (clock_->now ()
                                                      - begin_timestamp);
                trace::printf ("%s(0x%X,%u) in %d @%p %s >0x%X\n", __func__,
                               mask, mode, slept_ticks, this, name (),
                               event_flags_.mask ());
#endif
                return result::ok;
              }
            // ----- Exit critical section ------------------------------------
          }
 
          internal_suspend_ ();
 
          if (interrupted ())
            {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
              trace::printf ("%s(0x%X,%u) EINTR @%p %s\n", __func__, mask,
                             mode, this, name ());
#endif
              return EINTR;
            }
        }
 
      /* NOTREACHED */
      return ENOTRECOVERABLE;
    }
 
    result_t
    thread::internal_flags_try_wait_ (flags::mask_t mask,
                                      flags::mask_t* oflags,
                                      flags::mode_t mode)
    {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X,%u) @%p %s <0x%X\n", __func__, mask, mode, this,
                     name (), event_flags_.mask ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (event_flags_.check_raised (mask, oflags, mode))
          {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
            trace::printf ("%s(0x%X,%u) @%p %s >0x%X\n", __func__, mask, mode,
                           this, name (), event_flags_.mask ());
#endif
            return result::ok;
          }
        else
          {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
            trace::printf ("%s(0x%X,%u) EWOULDBLOCK @%p %s \n", __func__, mask,
                           mode, this, name ());
#endif
            return EWOULDBLOCK;
          }
        // ----- Exit critical section ----------------------------------------
      }
    }
 
    result_t
    thread::internal_flags_timed_wait_ (flags::mask_t mask,
                                        clock::duration_t timeout,
                                        flags::mask_t* oflags,
                                        flags::mode_t mode)
    {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X,%u,%u) @%p %s <0x%X\n", __func__, mask, timeout,
                     mode, this, name (), event_flags_.mask ());
#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);
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (event_flags_.check_raised (mask, oflags, mode))
          {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
            trace::printf ("%s(0x%X,%u,%u) @%p %s >0x%X\n", __func__, mask,
                           timeout, mode, this, name (), event_flags_.mask ());
#endif
            return result::ok;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      internal::clock_timestamps_list& clock_list = clock_->steady_list ();
      clock::timestamp_t timeout_timestamp = clock_->steady_now () + timeout;
 
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      clock::timestamp_t begin_timestamp = clock_->steady_now ();
#endif
 
      // Prepare a timeout node pointing to the current thread.
      internal::timeout_thread_node timeout_node{ timeout_timestamp, *this };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            if (event_flags_.check_raised (mask, oflags, mode))
              {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
                clock::duration_t slept_ticks
                    = static_cast<clock::duration_t> (clock_->steady_now ()
                                                      - begin_timestamp);
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
                trace::printf ("%s(0x%X,%u,%u) in %u @%p %s >0x%X\n", __func__,
                               mask, timeout, mode,
                               static_cast<unsigned int> (slept_ticks), this,
                               name (), event_flags_.mask ());
#pragma GCC diagnostic pop
#endif
                return result::ok;
              }
 
            // Remove this thread from the ready list, if there.
            port::this_thread::prepare_suspend ();
 
            // Add this thread to the clock timeout list.
            clock_list.link (timeout_node);
            timeout_node.thread.clock_node_ = &timeout_node;
 
            state_ = state::suspended;
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            // Remove the thread from the clock timeout list,
            // if not already removed by the timer.
            timeout_node.thread.clock_node_ = nullptr;
            timeout_node.unlink ();
            // ----- Exit critical section ------------------------------------
          }
 
          if (interrupted ())
            {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
              trace::printf ("%s(0x%X,%u,%u) EINTR @%p %s\n", __func__, mask,
                             timeout, mode, this, name ());
#endif
              return EINTR;
            }
 
          if (clock_->steady_now () >= timeout_timestamp)
            {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
              trace::printf ("%s(0x%X,%u,%u) ETIMEDOUT @%p %s\n", __func__,
                             mask, timeout, mode, this, name ());
#endif
              return ETIMEDOUT;
            }
        }
 
      return ENOTRECOVERABLE;
    }
 
    flags::mask_t
    thread::internal_flags_get_ (flags::mask_t mask, flags::mode_t mode)
    {
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X) @%p %s\n", __func__, mask, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), flags::all);
 
      flags::mask_t ret = event_flags_.get (mask, mode);
 
#if defined(OS_TRACE_RTOS_THREAD_FLAGS)
      trace::printf ("%s(0x%X)=0x%X @%p %s\n", __func__, mask,
                     event_flags_.mask (), this, name ());
#endif
      // Return the selected bits.
      return ret;
    }
 
    result_t
    thread::internal_flags_clear_ (flags::mask_t mask, flags::mask_t* oflags)
    {
#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
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      result_t res = event_flags_.clear (mask, oflags);
 
#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;
    }
 
    // ------------------------------------------------------------------------
    namespace this_thread
    {
 
      rtos::thread*
      _thread (void)
      {
        rtos::thread* th;
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
        th = port::this_thread::thread ();
 
#else
 
        th = scheduler::current_thread_;
 
#endif
        return th;
      }
 
      rtos::thread&
      thread (void)
      {
        // 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);
      }
 
      void
      yield (void)
      {
        // 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
      }
 
    } /* namespace this_thread */
 
    // ------------------------------------------------------------------------
  } /* namespace rtos */
} /* namespace os */
 
// ----------------------------------------------------------------------------