os-thread.h

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.
 */

#ifndef CMSIS_PLUS_RTOS_OS_THREAD_H_
#define CMSIS_PLUS_RTOS_OS_THREAD_H_

// ----------------------------------------------------------------------------

#if defined(__cplusplus)

#include <cmsis-plus/rtos/os-decls.h>
#include <cmsis-plus/rtos/os-clocks.h>
#include <cmsis-plus/rtos/internal/os-flags.h>

#if !defined(__ARM_EABI__)
#include <memory>
#endif

// ----------------------------------------------------------------------------

namespace
{
  // Anonymous definition required for the next forward definition.
  using _func_args_t = void*;
}

void
os_rtos_idle_actions (void);

namespace os
{
  namespace rtos
  {
    // ------------------------------------------------------------------------

    namespace this_thread
    {
      thread&
      thread (void);

      rtos::thread*
      _thread (void);

      void
      yield (void);

      void
      suspend (void);

      [[noreturn]] void
      exit (void* exit_ptr = nullptr);

      result_t
      flags_wait (flags::mask_t mask, flags::mask_t* oflags = nullptr,
                  flags::mode_t mode = flags::mode::all | flags::mode::clear);

      result_t
      flags_try_wait (
          flags::mask_t mask, flags::mask_t* oflags = nullptr,
          flags::mode_t mode = flags::mode::all | flags::mode::clear);

      result_t
      flags_timed_wait (
          flags::mask_t mask, clock::duration_t timeout, flags::mask_t* oflags =
              nullptr,
          flags::mode_t mode = flags::mode::all | flags::mode::clear);

      result_t
      flags_clear (flags::mask_t mask, flags::mask_t* oflags = nullptr);

      flags::mask_t
      flags_get (flags::mask_t mask,
                 flags::mode_t mode = flags::mode::all | flags::mode::clear);

      int*
      __errno (void);

    } /* namespace this_thread */

    // Forward definitions required by thread friends.
    namespace scheduler
    {

    } /* namespace scheduler */

    // ========================================================================

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wpadded"

    class thread : public internal::object_named_system
    {
    public:

      // Must be the very first, for easy access and to keep the
      // tiny thread used during initialisations to a minimum size.
      int errno_ = 0;

    public:

      // ======================================================================

      using priority_t = uint8_t;

      struct priority
      {
        static constexpr uint32_t range = 4;

        enum
          : priority_t
            {
              none = 0,

              idle = (1 << range),

              lowest = (2 << range),

              low = (2 << range),

              below_normal = (4 << range),

              normal = (6 << range),

              above_normal = (8 << range),

              high = (10 << range),

              realtime = (12 << range),

              highest = (((13 + 1) << range) - 1),

              isr = (((14 + 1) << range) - 1),

              error = (((15 + 1) << range) - 1)
        };
      }; /* struct priority */

      using state_t = uint8_t;

      struct state
      {
        enum
          : state_t
            {
              undefined = 0, //
          ready = 1, //
          running = 2, //
          suspended = 3, //
          terminated = 4, //
          destroyed = 5
        };
        /* enum  */
      }; /* struct state */

      using func_args_t = _func_args_t;

      using func_t = void* (*) (func_args_t args);

      // ======================================================================

      class stack
      {
      public:

        using element_t = os::rtos::port::stack::element_t;

        using allocation_element_t = os::rtos::port::stack::allocation_element_t;

        static const element_t magic = os::rtos::port::stack::magic;

        stack ();

        // The rule of five.
        stack (const stack&) = delete;
        stack (stack&&) = delete;
        stack&
        operator= (const stack&) = delete;
        stack&
        operator= (stack&&) = delete;

        ~stack () = default;

      public:

        void
        clear (void);

        void
        set (stack::element_t* address, std::size_t size_bytes);

        void
        initialize (void);

        stack::element_t*
        bottom (void);

        stack::element_t*
        top (void);

        std::size_t
        size (void);

        bool
        check_bottom_magic (void);

        bool
        check_top_magic (void);

        std::size_t
        available (void);

      public:

        static std::size_t
        min_size (void);

        static std::size_t
        min_size (std::size_t size_bytes);

        static std::size_t
        default_size (void);

        static std::size_t
        default_size (std::size_t size_bytes);

      protected:

        friend class rtos::thread;

        stack::element_t* bottom_address_;
        std::size_t size_bytes_;

        static std::size_t min_size_bytes_;
        static std::size_t default_size_bytes_;

      }; /* class stack */

      // ======================================================================
      class context
      {
      public:

        context ();

        // The rule of five.
        context (const context&) = delete;
        context (context&&) = delete;
        context&
        operator= (const context&) = delete;
        context&
        operator= (context&&) = delete;

        ~context () = default;

      public:

        thread::stack&
        stack (void);

      protected:

        friend class rtos::thread;
        friend class rtos::port::thread;
        friend void
        port::scheduler::start (void);
        friend void
        port::scheduler::reschedule ();

#if !defined(OS_USE_RTOS_PORT_SCHEDULER)

        friend class port::context;

        friend port::stack::element_t*
        port::scheduler::switch_stacks (port::stack::element_t* sp);

#endif

      protected:

        thread::stack stack_;

#if !defined(OS_USE_RTOS_PORT_SCHEDULER)

        port::thread_context_t port_;

#endif

      }; /* class context */

      // ======================================================================
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wpadded"

      class attributes : public internal::attributes_clocked
      {
      public:

        constexpr
        attributes ();

        // The rule of five.
        attributes (const attributes&) = default;
        attributes (attributes&&) = default;
        attributes&
        operator= (const attributes&) = default;
        attributes&
        operator= (attributes&&) = default;

        ~attributes () = default;

      public:

        // Public members; no accessors and mutators required.
        // Warning: must match the type & order of the C file header.
        void* th_stack_address = nullptr;

        std::size_t th_stack_size_bytes = 0;

        priority_t th_priority = priority::normal;

        // Add more attributes here.

      }; /* class attributes */

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) \
  || defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)

      class statistics
      {
      public:
        statistics () = default;

        // The rule of five.
        statistics (const statistics&) = delete;
        statistics (statistics&&) = delete;
        statistics&
        operator= (const statistics&) = delete;
        statistics&
        operator= (statistics&&) = delete;

        ~statistics () = default;

      public:

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES)

        rtos::statistics::counter_t
        context_switches (void);

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) */

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)

        rtos::statistics::duration_t
        cpu_cycles (void);

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES) */

      protected:

        friend void
        rtos::scheduler::internal_switch_threads (void);

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES)
        rtos::statistics::counter_t context_switches_ = 0;
#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) */

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)
        rtos::statistics::duration_t cpu_cycles_ = 0;
#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES) */

      };

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) || defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES) */

#pragma GCC diagnostic pop

      static const attributes initializer;

      // ======================================================================

      using allocator_type = memory::allocator<stack::allocation_element_t>;

      thread (func_t function, func_args_t args, const attributes& attr =
                  initializer,
              const allocator_type& allocator = allocator_type ());

      thread (const char* name, func_t function, func_args_t args,
              const attributes& attr = initializer,
              const allocator_type& allocator = allocator_type ());

    protected:

      // Internal constructors, used from templates.
      thread ();
      thread (const char* name);

    public:

      // The rule of five.
      thread (const thread&) = delete;
      thread (thread&&) = delete;
      thread&
      operator= (const thread&) = delete;
      thread&
      operator= (thread&&) = delete;

      virtual
      ~thread ();

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

    public:

      result_t
      cancel (void);

      result_t
      detach (void);

      result_t
      join (void** exit_ptr = nullptr);

      // Accessors & mutators.

      result_t
      priority (priority_t prio);

      result_t
      priority_inherited (priority_t prio);

      priority_t
      priority (void);

      priority_t
      priority_inherited (void);

#if 0
      // ???
      result_t
      set_cancel_state (int, int*);
      result_t
      set_cancel_type (int, int*);

      result_t
      get_sched_param (int*, struct sched_param*);
      result_t
      set_sched_param (int, const struct sched_param*);

      //void test_cancel(void);
#endif

      // TODO: study how to integrate signals and POSIX cancellation.
      bool
      interrupted (void);

      bool
      interrupt (bool interrupt = true);

      state_t
      state (void) const;

      void
      resume (void);

      void*
      function_args (void) const;

#if defined(OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE) || defined(__DOXYGEN__)

      os_thread_user_storage_t*
      user_storage (void);

#endif /* defined(OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE) */

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

#if defined(OS_INCLUDE_RTOS_THREAD_PUBLIC_FLAGS_CLEAR)

      // This is a kludge required to support CMSIS RTOS V1
      // public osSignalClear().
      result_t
      flags_clear (flags::mask_t mask, flags::mask_t* oflags);

#endif

      result_t
      kill (void);

      class thread::stack&
      stack (void);

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) \
  || defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)

      class thread::statistics&
      statistics (void);

#endif

    protected:

      friend class mutex;

      friend void
      this_thread::suspend (void);

      friend void
      this_thread::exit (void* exit_ptr);

      friend result_t
      this_thread::flags_wait (flags::mask_t mask, flags::mask_t* oflags,
                               flags::mode_t mode);

      friend result_t
      this_thread::flags_try_wait (flags::mask_t mask, flags::mask_t* oflags,
                                   flags::mode_t mode);
      friend result_t
      this_thread::flags_timed_wait (flags::mask_t mask,
                                     clock::duration_t timeout,
                                     flags::mask_t* oflags, flags::mode_t mode);

      friend result_t
      this_thread::flags_clear (flags::mask_t mask, flags::mask_t* oflags);

      friend flags::mask_t
      this_thread::flags_get (flags::mask_t mask, flags::mode_t mode);

      friend int*
      this_thread::__errno (void);

      friend void
      scheduler::internal_link_node (internal::waiting_threads_list& list,
                                     internal::waiting_thread_node& node);

      friend void
      scheduler::internal_unlink_node (internal::waiting_thread_node& node);

      friend void
      scheduler::internal_link_node (
          internal::waiting_threads_list& list,
          internal::waiting_thread_node& node,
          internal::clock_timestamps_list& timeout_list,
          internal::timeout_thread_node& timeout_node);

      friend void
      scheduler::internal_unlink_node (
          internal::waiting_thread_node& node,
          internal::timeout_thread_node& timeout_node);

      friend void
      scheduler::internal_switch_threads (void);

      friend void
      port::scheduler::reschedule (void);

      friend void
      port::scheduler::start (void);

      friend port::stack::element_t*
      port::scheduler::switch_stacks (port::stack::element_t* sp);

      friend void
      ::os_rtos_idle_actions (void);

      friend class internal::ready_threads_list;
      friend class internal::thread_children_list;
      friend class internal::waiting_threads_list;
      friend class internal::clock_timestamps_list;
      friend class internal::terminated_threads_list;

      friend class clock;
      friend class condition_variable;
      friend class mutex;

    protected:

      void
      internal_construct_ (func_t function, func_args_t args,
                           const attributes& attr, void* stack_address,
                           std::size_t stack_size_bytes);

      void
      internal_suspend_ (void);

      [[noreturn]]
      void
      internal_exit_ (void* exit_ptr = nullptr);

      [[noreturn]]
      static void
      internal_invoke_with_exit_ (thread* thread);

      result_t
      internal_flags_wait_ (flags::mask_t mask, flags::mask_t* oflags,
                            flags::mode_t mode);

      result_t
      internal_flags_try_wait_ (flags::mask_t mask, flags::mask_t* oflags,
                                flags::mode_t mode);

      result_t
      internal_flags_timed_wait_ (flags::mask_t mask, clock::duration_t timeout,
                                  flags::mask_t* oflags, flags::mode_t mode);

      bool
      internal_try_wait_ (flags::mask_t mask, flags::mask_t* oflags,
                          flags::mode_t mode);

      result_t
      internal_flags_clear_ (flags::mask_t mask, flags::mask_t* oflags);

      flags::mask_t
      internal_flags_get_ (flags::mask_t mask, flags::mode_t mode);

      virtual void
      internal_destroy_ (void);

      void
      internal_relink_running_ (void);

      void
      internal_check_stack_ (void);

    protected:

      // TODO: make it fully intrusive with computed offset.
      internal::waiting_thread_node ready_node_
        { *this };

      func_t func_ = nullptr;
      func_args_t func_args_ = nullptr;
      void* func_result_ = nullptr;

      // Pointer to parent, or null for top/detached thread.
      thread* parent_ = nullptr;

    public:

      // Intrusive node used to link this thread to parent list.
      utils::double_list_links child_links_;

      using threads_list = utils::intrusive_list<
      thread, utils::double_list_links, &thread::child_links_>;

      // List of children threads. Force a clear.
      threads_list children_
        { true };

      // List of mutexes that this thread owns.
      utils::double_list mutexes_;

    protected:

      // Thread waiting to join.
      thread* joiner_ = nullptr;

      // Pointer to waiting node (stored on stack)
      internal::waiting_thread_node* waiting_node_ = nullptr;

      // Pointer to timeout node (stored on stack)
      internal::timeout_thread_node* clock_node_ = nullptr;

      clock* clock_ = nullptr;

      const void* allocator_ = nullptr;

      stack::element_t* allocated_stack_address_ = nullptr;

      std::size_t allocated_stack_size_elements_ = 0;

      // TODO: Add a list, to properly process robustness.
      std::size_t volatile acquired_mutexes_ = 0;

      // The thread state is set:
      // - running - in ready_threads_list::unlink_head()
      // - ready - in ready_threads_list::link()
      // - waiting - in clock::internal_wait_until(),
      //              scheduler::internal_link_node()
      //              thread::_timed_flags_wait()
      // - terminated - in state::internal_exit_()
      // - destroyed - in thread::internal_destroy_()
      state_t volatile state_ = state::undefined;

      // There are two values used as thread priority. The main one is
      // assigned via `priority(int)`, and is stored in `prio_assigned_`.
      // This value is normally used by the scheduler.
      // However, to prevent priority inversion, mutexes might temporarily
      // boost priorities via `priority_inherited(int)`; this second
      // value is stored in `prio_inherited_`.

      // POSIX: While a thread is holding a mutex which has been
      // initialised with the mutex::protocol::inherit or
      // mutex::protocol::protect protocol attributes, it shall
      // not be subject to being moved to the tail of the scheduling
      // queue at its priority in the event that its original
      // priority is changed, such as by a POSIX call to sched_setparam().
      priority_t volatile prio_assigned_ = priority::none;
      priority_t volatile prio_inherited_ = priority::none;

      bool volatile interrupted_ = false;

      internal::event_flags event_flags_;

#if defined(OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE) || defined(__DOXYGEN__)
      os_thread_user_storage_t user_storage_;
#endif /* defined(OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE) */

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES)

      class statistics statistics_;

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) */

      // Add other internal data

      // Implementation
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
      friend class port::thread;
      os_thread_port_data_t port_;
#endif

      // Better be the last one!
      context context_;

    };
    /* class thread */

    template<typename Allocator = memory::allocator<void*>>
      class thread_allocated : public thread
      {
      public:

        using allocator_type = Allocator;

        thread_allocated (func_t function, func_args_t args,
                          const attributes& attr = initializer,
                          const allocator_type& allocator = allocator_type ());

        thread_allocated (const char* name, func_t function, func_args_t args,
                          const attributes& attr = initializer,
                          const allocator_type& allocator = allocator_type ());

        // The rule of five.
        thread_allocated (const thread_allocated&) = delete;
        thread_allocated (thread_allocated&&) = delete;
        thread_allocated&
        operator= (const thread_allocated&) = delete;
        thread_allocated&
        operator= (thread_allocated&&) = delete;

        virtual
        ~thread_allocated () override;

        virtual void
        internal_destroy_ (void) override;

      };

    template<std::size_t N = port::stack::default_size_bytes>
      class thread_inclusive : public thread
      {
      public:

        static const std::size_t stack_size_bytes = N;

        thread_inclusive (func_t function, func_args_t args,
                          const attributes& attr = initializer);

        thread_inclusive (const char* name, func_t function, func_args_t args,
                          const attributes& attr = initializer);

        // The rule of five.
        thread_inclusive (const thread_inclusive&) = delete;
        thread_inclusive (thread_inclusive&&) = delete;
        thread_inclusive&
        operator= (const thread_inclusive&) = delete;
        thread_inclusive&
        operator= (thread_inclusive&&) = delete;

        virtual
        ~thread_inclusive ();

      private:

        stack::allocation_element_t stack_[(stack_size_bytes
            + sizeof(stack::allocation_element_t) - 1)
            / sizeof(stack::allocation_element_t)];

      };

#pragma GCC diagnostic pop

  } /* namespace rtos */
} /* namespace os */

// ===== Inline & template implementations ====================================

namespace os
{
  namespace rtos
  {
    namespace this_thread
    {
      inline void
      suspend (void)
      {
        this_thread::thread ().internal_suspend_ ();
      }

      inline result_t
      flags_wait (flags::mask_t mask, flags::mask_t* oflags, flags::mode_t mode)
      {
        return this_thread::thread ().internal_flags_wait_ (mask, oflags, mode);
      }

      inline result_t
      flags_try_wait (flags::mask_t mask, flags::mask_t* oflags,
                      flags::mode_t mode)
      {
        return this_thread::thread ().internal_flags_try_wait_ (mask, oflags,
                                                                mode);
      }

      inline result_t
      flags_timed_wait (flags::mask_t mask, clock::duration_t timeout,
                        flags::mask_t* oflags, flags::mode_t mode)
      {
        return this_thread::thread ().internal_flags_timed_wait_ (mask, timeout,
                                                                  oflags, mode);
      }

      inline flags::mask_t
      flags_get (flags::mask_t mask, flags::mode_t mode)
      {
        return this_thread::thread ().internal_flags_get_ (mask, mode);
      }

      inline result_t
      flags_clear (flags::mask_t mask, flags::mask_t* oflags)
      {
        return this_thread::thread ().internal_flags_clear_ (mask, oflags);
      }

      inline void
      exit (void* exit_ptr)
      {
        this_thread::thread ().internal_exit_ (exit_ptr);
      }

      inline int*
      __attribute__ ((always_inline))
      __errno (void)
      {
        return &this_thread::thread ().errno_;
      }

    } /* namespace this_thread */

    constexpr
    thread::attributes::attributes ()
    {
      ;
    }

    // ======================================================================

    inline
    thread::stack::stack ()
    {
      clear ();
    }

    inline void
    thread::stack::clear (void)
    {
      bottom_address_ = nullptr;
      size_bytes_ = 0;
    }

    inline void
    thread::stack::set (stack::element_t* address, std::size_t size_bytes)
    {
      assert (size_bytes >= min_size_bytes_);
      bottom_address_ = address;
      size_bytes_ = size_bytes;
    }

    inline thread::stack::element_t*
    thread::stack::bottom (void)
    {
      return bottom_address_;
    }

    inline thread::stack::element_t*
    thread::stack::top (void)
    {
      return bottom_address_ + (size_bytes_ / sizeof(element_t));
    }

    inline std::size_t
    thread::stack::size (void)
    {
      return size_bytes_;
    }

    inline bool
    thread::stack::check_bottom_magic (void)
    {
      return *bottom () == stack::magic;
    }

    inline bool
    thread::stack::check_top_magic (void)
    {
      return *top () == stack::magic;
    }

    inline std::size_t
    thread::stack::min_size (void)
    {
      return min_size_bytes_;
    }

    inline std::size_t
    thread::stack::min_size (std::size_t size_bytes)
    {
      std::size_t tmp = min_size_bytes_;
      min_size_bytes_ = size_bytes;
      return tmp;
    }

    inline std::size_t
    thread::stack::default_size (void)
    {
      return default_size_bytes_;
    }

    inline std::size_t
    thread::stack::default_size (std::size_t size_bytes)
    {
      assert (size_bytes != 0);
      assert (size_bytes >= min_size_bytes_);

      std::size_t tmp = default_size_bytes_;
      default_size_bytes_ = size_bytes;
      return tmp;
    }

    // ========================================================================

    inline
    thread::context::context ()
    {
      ;
    }

    inline class thread::stack&
    thread::context::stack ()
    {
      return stack_;
    }

    // ========================================================================

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES)

    inline statistics::counter_t
    thread::statistics::context_switches (void)
    {
      return context_switches_;
    }

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) */

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)

    inline rtos::statistics::duration_t
    thread::statistics::cpu_cycles (void)
    {
      return cpu_cycles_;
    }

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES) */

    // ========================================================================

    inline bool
    thread::operator== (const thread& rhs) const
    {
      return this == &rhs;
    }

    inline thread::state_t
    thread::state (void) const
    {
      return state_;
    }

    inline void*
    thread::function_args (void) const
    {
      return func_args_;
    }

    inline bool
    thread::interrupted (void)
    {
      return interrupted_;
    }

#if defined(OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE) || defined(__DOXYGEN__)

    inline os_thread_user_storage_t*
    thread::user_storage (void)
      {
        return &user_storage_;
      }

#endif /* defined(OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE) */

#if !defined(OS_USE_RTOS_PORT_SCHEDULER)

    inline void
    thread::internal_relink_running_ (void)
    {
      if (state_ == state::running)
        {
          // If the current thread is running, add it to the
          // ready list, so that it will be resumed later.
          internal::waiting_thread_node& crt_node = ready_node_;
          if (crt_node.next () == nullptr)
            {
              rtos::scheduler::ready_threads_list_.link (crt_node);
              // Ready state set in above link().
            }

          // Simple test to verify that the old thread
          // did not underflow the stack.
          assert (stack ().check_bottom_magic ());
        }
    }

#endif

    inline class thread::stack&
    thread::stack (void)
    {
      return context_.stack_;
    }

#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES)

    inline class thread::statistics&
    thread::statistics (void)
    {
      return statistics_;
    }

#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) */

#if defined(OS_INCLUDE_RTOS_THREAD_PUBLIC_FLAGS_CLEAR)

    inline result_t
    thread::flags_clear (flags::mask_t mask, flags::mask_t* oflags)
    {
      return internal_flags_clear_ (mask, oflags);
    }

#endif

    // ========================================================================

    template<typename Allocator>
      inline
      thread_allocated<Allocator>::thread_allocated (
          func_t function, func_args_t args, const attributes& attr,
          const allocator_type& allocator) :
          thread_allocated
            { nullptr, function, args, attr, allocator }
      {
        ;
      }

    template<typename Allocator>
      thread_allocated<Allocator>::thread_allocated (
          const char* name, func_t function, func_args_t args,
          const attributes& attr, const allocator_type& allocator) :
          thread
            { name }
      {
#if defined(OS_TRACE_RTOS_THREAD)
        trace::printf ("%s @%p %s\n", __func__, this, this->name ());
#endif
        if (attr.th_stack_address != nullptr
            && attr.th_stack_size_bytes > stack::min_size ())
          {
            internal_construct_ (function, args, attr, nullptr, 0);
          }
        else
          {
            allocator_ = &allocator;

            if (attr.th_stack_size_bytes > stack::min_size ())
              {
                allocated_stack_size_elements_ = (attr.th_stack_size_bytes
                    + sizeof(typename allocator_type::value_type) - 1)
                    / sizeof(typename allocator_type::value_type);
              }
            else
              {
                allocated_stack_size_elements_ = (stack::default_size ()
                    + sizeof(typename allocator_type::value_type) - 1)
                    / sizeof(typename allocator_type::value_type);
              }

            // The reinterpret_cast<> is required since the allocator
            // uses allocation_element_t, which is usually larger.
            allocated_stack_address_ =
                reinterpret_cast<stack::element_t*> ((const_cast<allocator_type&> (allocator)).allocate (
                    allocated_stack_size_elements_));

            assert (allocated_stack_address_ != nullptr);

            internal_construct_ (
                function,
                args,
                attr,
                allocated_stack_address_,
                allocated_stack_size_elements_
                    * sizeof(typename allocator_type::value_type));
          }
      }

    template<typename Allocator>
      void
      thread_allocated<Allocator>::internal_destroy_ (void)
      {
#if defined(OS_TRACE_RTOS_THREAD)
        trace::printf ("thread_allocated::%s() @%p %s\n", __func__, this,
                       name ());
#endif

        if (allocated_stack_address_ != nullptr)
          {
            internal_check_stack_ ();

            typedef typename std::allocator_traits<allocator_type>::pointer pointer;

            static_cast<allocator_type*> (const_cast<void*> (allocator_))->deallocate (
                reinterpret_cast<pointer> (allocated_stack_address_),
                allocated_stack_size_elements_);

            allocated_stack_address_ = nullptr;
          }

        thread::internal_destroy_ ();
      }

    template<typename Allocator>
      thread_allocated<Allocator>::~thread_allocated ()
      {
#if defined(OS_TRACE_RTOS_THREAD)
        trace::printf ("%s @%p %s\n", __func__, this, name ());
#endif
      }

    // ========================================================================

    template<std::size_t N>
      inline
      thread_inclusive<N>::thread_inclusive (func_t function, func_args_t args,
                                             const attributes& attr) :
          thread_inclusive<N>
            { nullptr, function, args, attr }
      {
        ;
      }

    template<std::size_t N>
      thread_inclusive<N>::thread_inclusive (const char* name, func_t function,
                                             func_args_t args,
                                             const attributes& attr) :
          thread
            { name }
      {
#if defined(OS_TRACE_RTOS_THREAD)
        trace::printf ("%s @%p %s\n", __func__, this, this->name ());
#endif
        internal_construct_ (function, args, attr, &stack_, stack_size_bytes);
      }

    template<std::size_t N>
      thread_inclusive<N>::~thread_inclusive ()
      {
#if defined(OS_TRACE_RTOS_THREAD)
        trace::printf ("%s @%p %s\n", __func__, this, name ());
#endif
      }

  } /* namespace rtos */
} /* namespace os */

// ----------------------------------------------------------------------------

#endif /* __cplusplus */

#endif /* CMSIS_PLUS_RTOS_OS_THREAD_H_ */