os-mutex.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 Liviu Ionescu.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom
 * the Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 */
 
#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"
#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"
#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"
#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"
#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;
                      for (auto&& mx : *thread_mutexes)
                        {
                          if (mx.boosted_prio_ > max_prio)
                            {
                              max_prio = mx.boosted_prio_;
                            }
                        }
                      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)
      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 ());
#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::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;
 
                  for (auto&& th : list_)
                    {
                      thread::priority_t prio = th.priority ();
                      if (prio > max_prio)
                        {
                          max_prio = prio;
                        }
                    }
 
                  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 */
 
// ----------------------------------------------------------------------------