os-mutex.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>
 
// ----------------------------------------------------------------------------
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#endif
 
// ----------------------------------------------------------------------------
 
namespace os
{
  namespace rtos
  {
    // ------------------------------------------------------------------------
 
    const mutex::attributes mutex::initializer_normal;
 
    const mutex::attributes_recursive mutex::initializer_recursive;
 
    // ------------------------------------------------------------------------
 
    using mutexes_list = utils::intrusive_list<mutex, utils::double_list_links,
                                               &mutex::owner_links_>;
 
    // ------------------------------------------------------------------------
 
    mutex::mutex (const attributes& attr) : mutex{ nullptr, attr }
    {
    }
 
    mutex::mutex (const char* name, const attributes& attr)
        : object_named_system{ name }, //
          type_ (attr.mx_type), //
          protocol_ (attr.mx_protocol), //
          robustness_ (attr.mx_robustness), //
          max_count_ ((attr.mx_type == type::recursive) ? attr.mx_max_count
                                                        : 1)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      trace::printf ("%s() @%p %s\n", __func__, this, this->name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
 
      os_assert_throw (type_ <= type::max_, EINVAL);
      os_assert_throw (protocol_ <= protocol::max_, EINVAL);
      os_assert_throw (robustness_ <= robustness::max_, EINVAL);
 
#if !defined(OS_USE_RTOS_PORT_MUTEX)
      clock_ = attr.clock != nullptr ? attr.clock : &sysclock;
#endif
 
      os_assert_throw (attr.mx_priority_ceiling >= thread::priority::lowest,
                       EINVAL);
      os_assert_throw (attr.mx_priority_ceiling <= thread::priority::highest,
                       EINVAL);
 
      initial_prio_ceiling_ = attr.mx_priority_ceiling;
      prio_ceiling_ = attr.mx_priority_ceiling;
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      count_ = 0;
      port::mutex::create (this);
 
#else
 
      internal_init_ ();
 
#endif
    }
 
    mutex::~mutex ()
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      port::mutex::destroy (this);
 
#else
 
      // The mutex must have no owner (must have been unlocked).
      assert (owner_ == nullptr);
      // There must be no threads waiting for this mutex.
      assert (list_.empty ());
 
#endif
    }
 
    void
    mutex::internal_init_ (void)
    {
      owner_ = nullptr;
      owner_links_.unlink ();
      count_ = 0;
      prio_ceiling_ = initial_prio_ceiling_;
      boosted_prio_ = thread::priority::none;
      owner_dead_ = false;
      consistent_ = true;
      recoverable_ = true;
 
#if !defined(OS_USE_RTOS_PORT_MUTEX)
 
      // Wake-up all threads, if any.
      // Need not be inside the critical section,
      // the list is protected by inner `resume_one()`.
      list_.resume_all ();
 
#endif
    }
 
    /*
     * Internal function.
     * Should be called from a scheduler critical section.
     */
    result_t
    mutex::internal_try_lock_ (/* class */ thread* th)
    {
      // Save the initial owner for later protocol tests.
      thread* saved_owner = owner_;
 
      // First lock.
      if (owner_ == nullptr)
        {
          // If the mutex has no owner, own it.
          owner_ = th;
 
          // For recursive mutexes, initialise counter.
          count_ = 1;
 
          // Add mutex to the thread list.
          mutexes_list* th_list
              = reinterpret_cast<mutexes_list*> (&owner_->mutexes_);
          th_list->link (*this);
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wdeprecated-volatile"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wvolatile"
#endif
          // Count the number of mutexes acquired by the thread.
          ++(owner_->acquired_mutexes_);
#pragma GCC diagnostic pop
 
          if (protocol_ == protocol::protect)
            {
              if (th->priority () > prio_ceiling_)
                {
                  // No need to keep the lock.
                  owner_ = nullptr;
 
                  // Prio ceiling must be at least the priority of the
                  // highest priority thread.
                  return EINVAL;
                }
 
              // POSIX: When a thread owns one or more mutexes
              // initialised with the mutex::protocol::protect protocol,
              // it shall execute at the higher of its priority or the
              // highest of the priority ceilings of all the mutexes
              // owned by this thread and initialised with this
              // attribute, regardless of whether other threads are
              // blocked on any of these robust mutexes or not.
 
              // Boost priority.
              boosted_prio_ = prio_ceiling_;
              if (boosted_prio_ > owner_->priority_inherited ())
                {
                  // ----- Enter uncritical section ---------------------------
                  scheduler::uncritical_section sucs;
 
                  owner_->priority_inherited (boosted_prio_);
                  // ----- Exit uncritical section ----------------------------
                }
            }
 
#if defined(OS_TRACE_RTOS_MUTEX)
          trace::printf ("%s() @%p %s by %p %s LCK\n", __func__, this, name (),
                         th, th->name ());
#endif
          // If the owning thread of a robust mutex terminates while
          // holding the mutex lock, the next thread that acquires the
          // mutex may be notified about the termination by the return
          // value EOWNERDEAD.
          if (owner_dead_)
            {
              // TODO: decide if the lock must be preserved.
              return EOWNERDEAD;
            }
          return result::ok;
        }
 
      // Relock? (lock by the same thread).
      if (saved_owner == th)
        {
          // The mutex was requested again by the same thread.
          if (type_ == type::recursive)
            {
              if (count_ >= max_count_)
                {
                  // The recursive mutex reached its limit.
#if defined(OS_TRACE_RTOS_MUTEX)
                  trace::printf ("%s() @%p %s EAGAIN\n", __func__, this,
                                 name ());
#endif
                  return EAGAIN;
                }
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wdeprecated-volatile"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wvolatile"
#endif
              // Increment the recursion depth counter.
              ++count_;
#pragma GCC diagnostic pop
 
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() @%p %s by %p %s >%u\n", __func__, this,
                             name (), th, th->name (), count_);
#endif
              return result::ok;
            }
          else if (type_ == type::errorcheck)
            {
              // Errorcheck mutexes do not block, but return an error.
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() @%p %s EDEADLK\n", __func__, this, name ());
#endif
              return EDEADLK;
            }
          else if (type_ == type::normal)
            {
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() @%p %s deadlock\n", __func__, this,
                             name ());
#endif
              return EWOULDBLOCK;
            }
 
          return EWOULDBLOCK;
        }
      else
        {
          // Try to lock when not owner (another thread requested the mutex).
 
          // POSIX: When a thread makes a call to mutex::lock(), the mutex was
          // initialised with the protocol attribute having the value
          // mutex::protocol::inherit, when the calling thread is blocked
          // because the mutex is owned by another thread, that owner thread
          // shall inherit the priority level of the calling thread as long
          // as it continues to own the mutex. The implementation shall
          // update its execution priority to the maximum of its assigned
          // priority and all its inherited priorities.
          // Furthermore, if this owner thread itself becomes blocked on
          // another mutex with the protocol attribute having the value
          // mutex::protocol::inherit, the same priority inheritance effect
          // shall be propagated to this other owner thread, in a recursive
          // manner.
          if (protocol_ == protocol::inherit)
            {
              thread::priority_t prio = th->priority ();
              boosted_prio_ = prio;
 
              if (owner_links_.unlinked ())
                {
                  mutexes_list* th_list
                      = reinterpret_cast<mutexes_list*> (&owner_->mutexes_);
                  th_list->link (*this);
                }
 
              // Boost owner priority.
              if ((boosted_prio_ > owner_->priority_inherited ()))
                {
                  // ----- Enter uncritical section ---------------------------
                  scheduler::uncritical_section sucs;
 
                  owner_->priority_inherited (boosted_prio_);
                  // ----- Exit uncritical section ----------------------------
                }
 
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() @%p %s boost %u by %p %s \n", __func__,
                             this, name (), boosted_prio_, th, th->name ());
#endif
 
              return EWOULDBLOCK;
            }
        }
 
      // Block anyway.
      return EWOULDBLOCK;
    }
 
    result_t
    mutex::internal_unlock_ (thread* th)
    {
      if (!recoverable_)
        {
          return ENOTRECOVERABLE;
        }
 
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        // Is the rightful owner?
        if (owner_ == th)
          {
            if ((type_ == type::recursive) && (count_ > 1))
              {
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wdeprecated-volatile"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wvolatile"
#endif
                // Decrement the recursion depth counter.
                --count_;
#pragma GCC diagnostic pop
 
#if defined(OS_TRACE_RTOS_MUTEX)
                trace::printf ("%s() @%p %s >%u\n", __func__, this, name (),
                               count_);
#endif
                return result::ok;
              }
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wdeprecated-volatile"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wvolatile"
#endif
            --(owner_->acquired_mutexes_);
#pragma GCC diagnostic pop
 
            // Remove this mutex from the thread list; ineffective if
            // not linked.
            owner_links_.unlink ();
 
            if (boosted_prio_ != thread::priority::none)
              {
                mutexes_list* thread_mutexes
                    = reinterpret_cast<mutexes_list*> (&owner_->mutexes_);
 
                if (thread_mutexes->empty ())
                  {
                    // If the owner thread has no more mutexes,
                    // clear the inherited priority,
                    // and the assigned priority will take precedence.
                    boosted_prio_ = thread::priority::none;
                  }
                else
                  {
                    // If the owner thread acquired other mutexes too,
                    // compute the maximum boosted priority.
                    thread::priority_t max_prio = 0;
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Waggregate-return"
#endif
                    for (auto&& mx : *thread_mutexes)
                      {
                        if (mx.boosted_prio_ > max_prio)
                          {
                            max_prio = mx.boosted_prio_;
                          }
                      }
#pragma GCC diagnostic pop
                    boosted_prio_ = max_prio;
                  }
                // Delayed until end of critical section.
                owner_->priority_inherited (boosted_prio_);
              }
 
            // Delayed until end of critical section.
            list_.resume_one ();
 
            // Finally release the mutex.
            owner_ = nullptr;
            count_ = 0;
 
#if defined(OS_TRACE_RTOS_MUTEX)
            trace::printf ("%s() @%p %s ULCK\n", __func__, this, name ());
#endif
 
            // POSIX: If a robust mutex whose owner died is unlocked without
            // a call to consistent(), it shall be in a permanently
            // unusable state and all attempts to lock the mutex
            // shall fail with the error ENOTRECOVERABLE.
 
            if (owner_dead_)
              {
                owner_dead_ = false;
 
                if (!consistent_)
                  {
                    recoverable_ = false;
                    return ENOTRECOVERABLE;
                  }
              }
 
            return result::ok;
          }
 
        // Not owner, or not locked.
        if (type_ == type::errorcheck || type_ == type::recursive
            || robustness_ == robustness::robust)
          {
#if defined(OS_TRACE_RTOS_MUTEX)
            trace::printf ("%s() EPERM @%p %s \n", __func__, this, name ());
#endif
            return EPERM;
          }
 
          // Normal no-robust mutexes owned by other threads have
          // undefined behaviour.
 
#if defined(OS_TRACE_RTOS_MUTEX)
        trace::printf ("%s() ENOTRECOVERABLE @%p %s \n", __func__, this,
                       name ());
#endif
        return ENOTRECOVERABLE;
        // ----- Exit critical section ----------------------------------------
      }
    }
 
    // Called from thread termination, in a critical section.
    void
    mutex::internal_mark_owner_dead_ (void)
    {
      // May return error if not the rightful owner.
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
 
      if (robustness_ == mutex::robustness::robust)
        {
          // If the owning thread of a robust mutex terminates
          // while holding the mutex lock, the next thread that
          // acquires the mutex may be notified about the termination
          // by the return value EOWNERDEAD.
          owner_dead_ = true;
          consistent_ = false;
        }
    }
 
    result_t
    mutex::lock (void)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      trace::printf ("%s() @%p %s by %p %s\n", __func__, this, name (),
                     &this_thread::thread (), this_thread::thread ().name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't try to lock a non-recursive mutex again.
      os_assert_err (!scheduler::locked (), EPERM);
 
      if (!recoverable_)
        {
          return ENOTRECOVERABLE;
        }
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      return port::mutex::lock (this);
 
#else
 
      thread& crt_thread = this_thread::thread ();
 
      result_t res;
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        res = internal_try_lock_ (&crt_thread);
        if (res != EWOULDBLOCK)
          {
            return res;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      // Prepare a list node pointing to the current thread.
      // Do not worry for being on stack, it is temporarily linked to the
      // list and guaranteed to be removed before this function returns.
      internal::waiting_thread_node node{ crt_thread };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            scheduler::critical_section scs;
 
            res = internal_try_lock_ (&crt_thread);
            if (res != EWOULDBLOCK)
              {
                return res;
              }
 
            {
              // ----- Enter critical section -----------------------------
              interrupts::critical_section ics;
 
              // Add this thread to the mutex waiting list.
              scheduler::internal_link_node (list_, node);
              // state::suspended set in above link().
              // ----- Exit critical section ------------------------------
            }
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the semaphore waiting list,
          // if not already removed by unlock().
          scheduler::internal_unlink_node (node);
 
          if (crt_thread.interrupted ())
            {
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() EINTR @%p %s\n", __func__, this, name ());
#endif
              return EINTR;
            }
        }
 
      /* NOTREACHED */
      return ENOTRECOVERABLE;
 
#endif
    }
 
    result_t
    mutex::try_lock (void)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      trace::printf ("%s() @%p %s by %p %s\n", __func__, this, name (),
                     &this_thread::thread (), this_thread::thread ().name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      if (!recoverable_)
        {
          return ENOTRECOVERABLE;
        }
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      return port::mutex::try_lock (this);
 
#else
 
      thread& crt_thread = this_thread::thread ();
 
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        return internal_try_lock_ (&crt_thread);
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
    }
 
    result_t
    mutex::timed_lock (clock::duration_t timeout)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
      trace::printf ("%s(%u) @%p %s by %p %s\n", __func__,
                     static_cast<unsigned int> (timeout), this, name (),
                     &this_thread::thread (), this_thread::thread ().name ());
#pragma GCC diagnostic pop
#endif /* defined(OS_TRACE_RTOS_MUTEX) */
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
      // Don't try to lock a non-recursive mutex again.
      os_assert_err (!scheduler::locked (), EPERM);
 
      if (!recoverable_)
        {
          return ENOTRECOVERABLE;
        }
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      return port::mutex::timed_lock (this, timeout);
 
#else
 
      thread& crt_thread = this_thread::thread ();
 
      result_t res;
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        scheduler::critical_section scs;
 
        res = internal_try_lock_ (&crt_thread);
        if (res != EWOULDBLOCK)
          {
            return res;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      // Prepare a list node pointing to the current thread.
      // Do not worry for being on stack, it is temporarily linked to the
      // list and guaranteed to be removed before this function returns.
      internal::waiting_thread_node node{ crt_thread };
 
      internal::clock_timestamps_list& clock_list = clock_->steady_list ();
      clock::timestamp_t timeout_timestamp = clock_->steady_now () + timeout;
 
      // Prepare a timeout node pointing to the current thread.
      internal::timeout_thread_node timeout_node{ timeout_timestamp,
                                                  crt_thread };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            scheduler::critical_section scs;
 
            res = internal_try_lock_ (&crt_thread);
            if (res != EWOULDBLOCK)
              {
                return res;
              }
 
            {
              // ----- Enter critical section -----------------------------
              interrupts::critical_section ics;
 
              // Add this thread to the mutex waiting list,
              // and the clock timeout list.
              scheduler::internal_link_node (list_, node, clock_list,
                                             timeout_node);
              // state::suspended set in above link().
              // ----- Exit critical section ------------------------------
            }
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the semaphore waiting list,
          // if not already removed by unlock() and from the clock
          // timeout list, if not already removed by the timer.
          scheduler::internal_unlink_node (node, timeout_node);
 
          res = result::ok;
 
          if (crt_thread.interrupted ())
            {
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() EINTR @%p %s \n", __func__, this, name ());
#endif
              res = EINTR;
            }
          else if (clock_->steady_now () >= timeout_timestamp)
            {
#if defined(OS_TRACE_RTOS_MUTEX)
              trace::printf ("%s() ETIMEDOUT @%p %s \n", __func__, this,
                             name ());
#endif
              res = ETIMEDOUT;
            }
          if (res != result::ok)
            {
              if (boosted_prio_ != thread::priority::none)
                {
                  // If the priority was boosted, it must be restored
                  // to the highest priority of the waiting threads, if any.
 
                  thread::priority_t max_prio = thread::priority::none;
 
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Waggregate-return"
#endif
                  for (auto&& th : list_)
                    {
                      thread::priority_t prio = th.priority ();
                      if (prio > max_prio)
                        {
                          max_prio = prio;
                        }
                    }
#pragma GCC diagnostic pop
 
                  if (max_prio != thread::priority::none)
                    {
                      boosted_prio_ = max_prio;
                      owner_->priority (boosted_prio_);
                    }
                }
              return res;
            }
        }
 
      /* NOTREACHED */
      return ENOTRECOVERABLE;
 
#endif
    }
 
    result_t
    mutex::unlock (void)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      trace::printf ("%s() @%p %s by %p %s\n", __func__, this, name (),
                     &this_thread::thread (), this_thread::thread ().name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      return port::mutex::unlock (this);
 
#else
 
      thread* crt_thread = &this_thread::thread ();
 
      return internal_unlock_ (crt_thread);
 
#endif
    }
 
    thread::priority_t
    mutex::prio_ceiling (void) const
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      assert (!interrupts::in_handler_mode ());
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      return port::mutex::prio_ceiling (this);
 
#else
 
      return prio_ceiling_;
 
#endif
    }
 
    result_t
    mutex::prio_ceiling (thread::priority_t prio_ceiling,
                         thread::priority_t* old_prio_ceiling)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      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_MUTEX)
 
      return port::mutex::prio_ceiling (this, prio_ceiling, old_prio_ceiling);
 
#else
 
      // TODO: lock() must not adhere to the priority protocol.
      result_t res = lock ();
      if (res != result::ok)
        {
          return res;
        }
 
      if (old_prio_ceiling != nullptr)
        {
          *old_prio_ceiling = prio_ceiling_;
        }
 
      prio_ceiling_ = prio_ceiling;
 
      unlock ();
 
      return result::ok;
 
#endif
    }
 
    result_t
    mutex::consistent (void)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      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 for non-robust mutexes.
      os_assert_err (robustness_ == robustness::robust, EINVAL);
      // Don't call it if already consistent.
      os_assert_err (!consistent_, EINVAL);
 
#if defined(OS_USE_RTOS_PORT_MUTEX)
 
      return port::mutex::consistent (this);
 
#else
 
      // Update status to consistent.
      consistent_ = true;
      return result::ok;
 
#endif
    }
 
    result_t
    mutex::reset (void)
    {
#if defined(OS_TRACE_RTOS_MUTEX)
      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;
 
        internal_init_ ();
        return result::ok;
        // ----- Exit critical section ----------------------------------------
      }
    }
 
    // ========================================================================
 
    // ------------------------------------------------------------------------
  } /* namespace rtos */
} /* namespace os */
 
// ----------------------------------------------------------------------------