os-thread.cpp

Go to the documentation of this file.

/*
 * This file is part of the µOS++ distribution.
 *   (https://github.com/micro-os-plus)
 * Copyright (c) 2016-2023 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);
 
      element_t* p = bottom_address_;
      element_t* pend = top ();
 
      // Initialise the entire stack with the magic word.
      for (; p < pend; ++p)
        {
          *p = magic;
        }
 
      // 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)
    {
      element_t* p = bottom_address_;
      std::size_t count = 0;
      while (*p == magic)
        {
          count += sizeof(element_t);
          ++p;
        }
 
      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 */
 
// ----------------------------------------------------------------------------