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
 
// ----------------------------------------------------------------------------
 
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
#endif
 
// ----------------------------------------------------------------------------
 
namespace
{
  // Anonymous definition required for the next forward definition.
  using _func_args_t = void*;
}
 
void
os_rtos_idle_actions (void);
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#endif
#pragma GCC diagnostic pop
 
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, //
          initializing = 6 //
        };
        /* 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;
 
        bool th_enable_assert_reuse = false;
 
        // 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) */
 
        void
        clear (void);
 
      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:
 
      static bool
      is_constructed(const thread& thread);
 
      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_()
      // DO NOT initialise here, it is used to check for reuse.
      state_t volatile state_; // = state::initializing;
 
      // 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 () override;
 
      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) */
 
#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) \
  || defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)
 
    inline void
    thread::statistics::clear (void) {
#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES)
      context_switches_ = 0;
#endif /* defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CONTEXT_SWITCHES) */
 
#if defined(OS_INCLUDE_RTOS_STATISTICS_THREAD_CPU_CYCLES)
      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) */
 
    // ========================================================================
 
    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)
 
    // Runs during context switches, on the
    // scheduler timer interrupt context, for the thread being
    // switched out.
    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.
          if (!stack ().check_bottom_magic ())
            {
              // The `\n` is intentional, to make the message more readable,
              // since it can occur inside another message.
              trace::printf("\n%s() @%p %s\n", __func__, this, name ());
              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 */
 
#pragma GCC diagnostic pop
 
// ----------------------------------------------------------------------------
 
#endif /* __cplusplus */
 
// ----------------------------------------------------------------------------
 
#endif /* CMSIS_PLUS_RTOS_OS_THREAD_H_ */