os-mutex.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2016-2025 Liviu Ionescu. All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software
 * for any purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can
 * be obtained from https://opensource.org/licenses/mit.
 */
 
#ifndef CMSIS_PLUS_RTOS_OS_MUTEX_H_
#define CMSIS_PLUS_RTOS_OS_MUTEX_H_
 
// ----------------------------------------------------------------------------
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#include <cmsis-plus/rtos/os-decls.h>
 
// ----------------------------------------------------------------------------
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
#endif
 
// ----------------------------------------------------------------------------
 
namespace os
{
  namespace rtos
  {
    // ========================================================================
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
    class mutex : public internal::object_named_system
    {
    public:
      using protocol_t = uint8_t;
 
      struct protocol
      {
        enum : protocol_t
        {
          none = 0,
 
          inherit = 1,
 
          protect = 2,
 
          default_ = inherit,
 
          max_ = protect
        };
      };
 
      using robustness_t = uint8_t;
 
      struct robustness
      {
        enum : robustness_t
        {
          stalled = 0,
 
          robust = 1,
 
          default_ = stalled,
 
          max_ = robust
        };
      };
 
      using type_t = uint8_t;
 
      struct type
      {
        enum : type_t
        {
          normal = 0,
          errorcheck = 1,
          recursive = 2,
 
          default_ = normal,
 
          max_ = recursive
        };
      };
 
      using count_t = uint16_t;
 
      static constexpr count_t max_count = 0xFFFF;
 
      // ======================================================================
 
      class attributes : public internal::attributes_clocked
      {
      public:
        constexpr attributes ();
 
      protected:
        constexpr attributes (type_t type);
 
      public:
        // 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.
        thread::priority_t mx_priority_ceiling = thread::priority::highest;
 
        protocol_t mx_protocol = protocol::default_;
 
        robustness_t mx_robustness = robustness::stalled;
 
        type_t mx_type = type::default_;
 
        count_t mx_max_count = max_count;
 
        // Add more attributes here.
 
      }; /* class attributes */
 
      static const attributes initializer_normal;
 
      // ======================================================================
 
      class attributes_recursive : public attributes
      {
      public:
        constexpr attributes_recursive ();
 
        // The rule of five.
        attributes_recursive (const attributes_recursive&) = default;
        attributes_recursive (attributes_recursive&&) = default;
        attributes_recursive&
        operator= (const attributes_recursive&)
            = default;
        attributes_recursive&
        operator= (attributes_recursive&&)
            = default;
 
        ~attributes_recursive () = default;
 
      }; /* class attributes_recursive */
 
      static const attributes_recursive initializer_recursive;
 
      mutex (const attributes& attr = initializer_normal);
 
      mutex (const char* name, const attributes& attr = initializer_normal);
 
      // The rule of five.
      mutex (const mutex&) = delete;
      mutex (mutex&&) = delete;
      mutex&
      operator= (const mutex&)
          = delete;
      mutex&
      operator= (mutex&&)
          = delete;
 
      ~mutex ();
 
      bool
      operator== (const mutex& rhs) const;
 
    public:
      result_t
      lock (void);
 
      result_t
      try_lock (void);
 
      result_t
      timed_lock (clock::duration_t timeout);
 
      result_t
      unlock (void);
 
      thread::priority_t
      prio_ceiling (void) const;
 
      result_t
      prio_ceiling (thread::priority_t prio_ceiling,
                    thread::priority_t* old_prio_ceiling = nullptr);
 
      result_t
      consistent (void);
 
      thread*
      owner (void);
 
      type_t
      type (void);
 
      protocol_t
      protocol (void);
 
      robustness_t
      robustness (void);
 
      result_t
      reset (void);
 
    protected:
      friend class thread;
 
      void
      internal_init_ (void);
 
      result_t
      internal_try_lock_ (thread* th);
 
      result_t
      internal_unlock_ (thread* th);
 
      void
      internal_mark_owner_dead_ (void);
 
    protected:
      // Can be updated in different thread contexts.
      thread* volatile owner_ = nullptr;
 
#if !defined(OS_USE_RTOS_PORT_MUTEX)
      internal::waiting_threads_list list_;
      clock* clock_ = nullptr;
#endif
 
    public:
      // Intrusive node used to link this mutex to the owning thread.
      // This is used for priority inheritance and robustness.
      utils::double_list_links owner_links_;
 
    protected:
#if defined(OS_USE_RTOS_PORT_MUTEX)
      friend class port::mutex;
      os_mutex_port_data_t port_;
#endif
 
      // Can be updated in different thread contexts.
      volatile count_t count_ = 0;
 
      // Can be updated in different thread contexts.
      volatile thread::priority_t initial_prio_ceiling_
          = thread::priority::highest;
      volatile thread::priority_t prio_ceiling_ = thread::priority::highest;
      volatile thread::priority_t boosted_prio_ = thread::priority::none;
 
      bool owner_dead_ = false;
      bool consistent_ = true;
      bool recoverable_ = true;
 
      // Constants set during construction.
      const type_t type_; // normal, errorcheck, recursive
      const protocol_t protocol_; // none, inherit, protect
      const robustness_t robustness_; // stalled, robust
      const count_t max_count_;
 
      // Add more internal data.
 
    };
 
    class mutex_recursive : public mutex
    {
    public:
      mutex_recursive (const attributes& attr = initializer_recursive);
 
      mutex_recursive (const char* name,
                       const attributes& attr = initializer_recursive);
 
      // The rule of five.
      mutex_recursive (const mutex_recursive&) = delete;
      mutex_recursive (mutex_recursive&&) = delete;
      mutex_recursive&
      operator= (const mutex_recursive&)
          = delete;
      mutex_recursive&
      operator= (mutex_recursive&&)
          = delete;
 
      ~mutex_recursive ();
 
      bool
      operator== (const mutex_recursive& rhs) const;
 
    };
 
#pragma GCC diagnostic pop
 
    // ========================================================================
 
  } /* namespace rtos */
} /* namespace os */
 
// ===== Inline & template implementations ====================================
 
namespace os
{
  namespace rtos
  {
 
    // ========================================================================
 
    constexpr mutex::attributes::attributes ()
    {
    }
 
    constexpr mutex::attributes::attributes (type_t type) : mx_type (type)
    {
    }
 
    // ========================================================================
    constexpr mutex::attributes_recursive::attributes_recursive ()
        : attributes{ type::recursive } // Use the protected constructor.
    {
    }
 
    // ========================================================================
 
    inline bool
    mutex::operator== (const mutex& rhs) const
    {
      return this == &rhs;
    }
 
    inline thread*
    mutex::owner (void)
    {
      return owner_;
    }
 
    inline mutex::type_t
    mutex::type (void)
    {
      return type_;
    }
 
    inline mutex::protocol_t
    mutex::protocol (void)
    {
      return protocol_;
    }
 
    inline mutex::robustness_t
    mutex::robustness (void)
    {
      return robustness_;
    }
 
    // ========================================================================
 
    inline mutex_recursive::mutex_recursive (const attributes& attr)
        : mutex{ attr }
    {
    }
 
    inline mutex_recursive::mutex_recursive (const char* name,
                                             const attributes& attr)
        : mutex{ name, attr }
    {
    }
 
    inline mutex_recursive::~mutex_recursive ()
    {
    }
 
    inline bool
    mutex_recursive::operator== (const mutex_recursive& rhs) const
    {
      return this == &rhs;
    }
 
  } /* namespace rtos */
} /* namespace os */
 
#pragma GCC diagnostic pop
 
// ----------------------------------------------------------------------------
 
#endif /* __cplusplus */
 
// ----------------------------------------------------------------------------
 
#endif /* CMSIS_PLUS_RTOS_OS_MUTEX_H_ */