os-memory.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_MEMORY_H_
#define CMSIS_PLUS_RTOS_OS_MEMORY_H_

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

#if defined(__cplusplus)

#include <cmsis-plus/estd/system_error>

#include <limits>
#include <new>
#include <cerrno>
#include <mutex>

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

// These definitions refer only to the RTOS allocators.
// The application should use the similar ones from the
// os::estd:: namespace.

namespace os
{
  namespace estd
  {
    [[noreturn]] void
    __throw_bad_alloc (void);

    template<typename L>
      class lock_guard;

  }

  namespace rtos
  {
    namespace scheduler
    {
      class critical_section;
    }

    class null_locker;

    namespace memory
    {
      // ----------------------------------------------------------------------

      constexpr std::size_t
      max (std::size_t a, std::size_t b)
      {
        return (a >= b) ? a : b;
      }

      constexpr std::size_t
      align_size (std::size_t size, std::size_t align) noexcept
      {
        return ((size) + (align) - 1L) & ~((align) - 1L);
      }

      class memory_resource;

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

      memory_resource*
      malloc_resource (void) noexcept;

      memory_resource*
      set_default_resource (memory_resource* res) noexcept;

      memory_resource*
      get_default_resource (void) noexcept;

      void
      init_once_default_resource (void);

      // ======================================================================
      using out_of_memory_handler_t = void (*)(void);

      class memory_resource : public internal::object_named
      {

      public:

        static constexpr std::size_t max_align = alignof(std::max_align_t);

        memory_resource () = default;

        memory_resource (const char* name);

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

        virtual
        ~memory_resource ();

      public:

        void*
        allocate (std::size_t bytes, std::size_t alignment = max_align);

        void
        deallocate (void* addr, std::size_t bytes, std::size_t alignment =
                        max_align) noexcept;

        bool
        is_equal (memory_resource const & other) const noexcept;

        void
        reset (void) noexcept;

        bool
        coalesce (void) noexcept;

        std::size_t
        max_size (void) const noexcept;

        out_of_memory_handler_t
        out_of_memory_handler (out_of_memory_handler_t handler);

        out_of_memory_handler_t
        out_of_memory_handler (void);

        std::size_t
        total_bytes (void);

        std::size_t
        allocated_bytes (void);

        std::size_t
        max_allocated_bytes (void);

        std::size_t
        free_bytes (void);

        std::size_t
        allocated_chunks (void);

        std::size_t
        free_chunks (void);

        std::size_t
        allocations (void);

        std::size_t
        deallocations (void);

        void
        trace_print_statistics (void);

      protected:

        virtual void*
        do_allocate (std::size_t bytes, std::size_t alignment) = 0;

        virtual void
        do_deallocate (void* addr, std::size_t bytes, std::size_t alignment)
            noexcept = 0;

        virtual bool
        do_is_equal (memory_resource const &other) const noexcept;

        virtual std::size_t
        do_max_size (void) const noexcept;

        virtual void
        do_reset (void) noexcept;

        virtual bool
        do_coalesce (void) noexcept;

        void
        internal_increase_allocated_statistics (std::size_t bytes) noexcept;

        void
        internal_decrease_allocated_statistics (std::size_t bytes) noexcept;

      protected:

        out_of_memory_handler_t out_of_memory_handler_ = nullptr;

        std::size_t total_bytes_ = 0;
        std::size_t allocated_bytes_ = 0;
        std::size_t free_bytes_ = 0;
        std::size_t allocated_chunks_ = 0;
        std::size_t free_chunks_ = 0;
        std::size_t max_allocated_bytes_ = 0;
        std::size_t allocations_ = 0;
        std::size_t deallocations_ = 0;

      };

      bool
      operator== (const memory_resource& lhs, const memory_resource& rhs)
          noexcept;

      bool
      operator!= (const memory_resource& lhs, const memory_resource& rhs)
          noexcept;

      // ======================================================================
      template<typename T>
        class allocator_stateless_default_resource
        {
        public:

          using value_type = T;

          allocator_stateless_default_resource () noexcept = default;

          allocator_stateless_default_resource (
              allocator_stateless_default_resource const & other) = default;

          template<typename U>
            allocator_stateless_default_resource (
                allocator_stateless_default_resource<U> const & other) noexcept;

          allocator_stateless_default_resource (
              allocator_stateless_default_resource && other) = default;

          ~allocator_stateless_default_resource () = default;

          allocator_stateless_default_resource&
          operator= (allocator_stateless_default_resource const & other) = default;

          allocator_stateless_default_resource&
          operator= (allocator_stateless_default_resource && other) = default;

        public:

          value_type*
          allocate (std::size_t elements);

          void
          deallocate (value_type* addr, std::size_t elements) noexcept;

          std::size_t
          max_size (void) const noexcept;

        protected:

          // This class should have no member variables, to meet the
          // default allocator stateless requirements.
        };

      // ======================================================================
      template<typename L>
        class lock_guard;

      using F = memory_resource* (void);

      template<typename T, typename L, F get_resource>
        class allocator_stateless_polymorphic_synchronized
        {
        public:

          using value_type = T;
          using locker_type = L;

          allocator_stateless_polymorphic_synchronized () noexcept;

          allocator_stateless_polymorphic_synchronized (
              allocator_stateless_polymorphic_synchronized const & other) = default;

          template<typename U>
            allocator_stateless_polymorphic_synchronized (
                allocator_stateless_polymorphic_synchronized<U, L, get_resource> const & other)
                    noexcept;

          allocator_stateless_polymorphic_synchronized (
              allocator_stateless_polymorphic_synchronized && other) = default;

          ~allocator_stateless_polymorphic_synchronized () = default;

          allocator_stateless_polymorphic_synchronized&
          operator= (allocator_stateless_polymorphic_synchronized const & other) = default;

          allocator_stateless_polymorphic_synchronized&
          operator= (allocator_stateless_polymorphic_synchronized && other) = default;

        public:

          template<typename U>
            struct rebind
            {
              using other = allocator_stateless_polymorphic_synchronized<U, L, get_resource>;
            };

          value_type*
          allocate (std::size_t elements);

          void
          deallocate (value_type* addr, std::size_t elements) noexcept;

          std::size_t
          max_size (void) const noexcept;

#if 0
          allocator_stateless_polymorphic_synchronized
          select_on_container_copy_construction (void) const noexcept;

          memory_resource*
          resource (void) const noexcept;
#endif

        private:

          // This class should have no member variables, to meet the
          // default allocator stateless requirements.
        };

      template<typename T1, typename T2, typename L, F get_resource>
        bool
        operator== (
            const allocator_stateless_polymorphic_synchronized<T1, L,
                get_resource>& lhs,
            const allocator_stateless_polymorphic_synchronized<T2, L,
                get_resource>& rhs) noexcept;

      template<typename T1, typename T2, typename L, F get_resource>
        bool
        operator!= (
            const allocator_stateless_polymorphic_synchronized<T1, L,
                get_resource>& lhs,
            const allocator_stateless_polymorphic_synchronized<T2, L,
                get_resource>& rhs) noexcept;

      template<typename A>
        class allocator_deleter
        {
        public:

          using allocator_type = A;

          using allocator_traits = std::allocator_traits<A>;

          using pointer = typename allocator_traits::pointer;

          allocator_deleter ();

          allocator_deleter (const allocator_type& other);

          allocator_deleter (allocator_deleter&& other) = default;

          ~allocator_deleter () = default;

          allocator_deleter&
          operator= (const allocator_deleter& other) = default;

          allocator_deleter&
          operator= (allocator_deleter&& other) = default;

          void
          operator() (pointer addr) const;

        protected:

          allocator_type a_;

        };

      template<typename T, typename A, typename ... Args>
        auto
        allocate_unique (const A& allocator, Args&&... args);

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

      template<typename T>
        memory_resource*
        set_resource_typed (memory_resource* res) noexcept;

      template<typename T>
        memory_resource*
        get_resource_typed (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<thread> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<thread> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<condition_variable> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<condition_variable> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<event_flags> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<event_flags> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<memory_pool> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<memory_pool> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<message_queue> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<message_queue> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<mutex> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<mutex> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<semaphore> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<semaphore> (void) noexcept;

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

      template<>
        memory_resource*
        set_resource_typed<timer> (memory_resource* res) noexcept;

      template<>
        memory_resource*
        get_resource_typed<timer> (void) noexcept;

      // ----------------------------------------------------------------------
      template<typename T, typename U = T>
        using allocator_typed = allocator_stateless_polymorphic_synchronized<T, scheduler::lockable, get_resource_typed<U>>;

      template<typename T, typename U = T>
        using unique_ptr = std::unique_ptr<T, allocator_deleter<allocator_typed<T, U>>>;

    // ------------------------------------------------------------------------
    } /* namespace memory */
  } /* namespace rtos */
} /* namespace os */

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

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

      extern memory_resource* default_resource;

      extern memory_resource* resource_thread;
      extern memory_resource* resource_condition_variable;
      extern memory_resource* resource_event_flags;
      extern memory_resource* resource_memory_pool;
      extern memory_resource* resource_message_queue;
      extern memory_resource* resource_mutex;
      extern memory_resource* resource_semaphore;
      extern memory_resource* resource_timer;

      // ----------------------------------------------------------------------
      inline memory_resource*
      get_default_resource (void) noexcept
      {
        rtos::memory::init_once_default_resource ();
        return default_resource;
      }

      template<>
        inline memory_resource*
        get_resource_typed<thread> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_thread;
        }

      template<>
        inline memory_resource*
        get_resource_typed<condition_variable> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_condition_variable;
        }

      template<>
        inline memory_resource*
        get_resource_typed<event_flags> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_event_flags;
        }

      template<>
        inline memory_resource*
        get_resource_typed<memory_pool> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_memory_pool;
        }

      template<>
        inline memory_resource*
        get_resource_typed<message_queue> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_message_queue;
        }

      template<>
        inline memory_resource*
        get_resource_typed<mutex> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_mutex;
        }

      template<>
        inline memory_resource*
        get_resource_typed<semaphore> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_semaphore;
        }

      template<>
        inline memory_resource*
        get_resource_typed<timer> (void) noexcept
        {
          rtos::memory::init_once_default_resource ();
          return resource_timer;
        }

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

      inline
      memory_resource::memory_resource (const char* name) :
          object_named
            { name }
      {
        ;
      }

      inline void*
      memory_resource::allocate (std::size_t bytes, std::size_t alignment)
      {
        ++allocations_;
        return do_allocate (bytes, alignment);
      }

      inline void
      memory_resource::deallocate (void* addr, std::size_t bytes,
                                   std::size_t alignment) noexcept
      {
        ++deallocations_;
        do_deallocate (addr, bytes, alignment);
      }

      inline bool
      memory_resource::is_equal (memory_resource const & other) const noexcept
      {
        return do_is_equal (other);
      }

      inline std::size_t
      memory_resource::max_size (void) const noexcept
      {
        return do_max_size ();
      }

      inline void
      memory_resource::reset (void) noexcept
      {
        do_reset ();
      }

      inline bool
      memory_resource::coalesce (void) noexcept
      {
        return do_coalesce ();
      }

      inline out_of_memory_handler_t
      memory_resource::out_of_memory_handler (out_of_memory_handler_t handler)
      {
        trace::printf ("%s(%p) @%p %s\n", __func__, handler, this, name ());

        out_of_memory_handler_t tmp = out_of_memory_handler_;
        out_of_memory_handler_ = handler;

        return tmp;
      }

      inline out_of_memory_handler_t
      memory_resource::out_of_memory_handler (void)
      {
        return out_of_memory_handler_;
      }

      inline std::size_t
      memory_resource::total_bytes (void)
      {
        return total_bytes_;
      }

      inline std::size_t
      memory_resource::allocated_bytes (void)
      {
        return allocated_bytes_;
      }

      inline std::size_t
      memory_resource::max_allocated_bytes (void)
      {
        return max_allocated_bytes_;
      }

      inline std::size_t
      memory_resource::free_bytes (void)
      {
        return free_bytes_;
      }

      inline std::size_t
      memory_resource::allocated_chunks (void)
      {
        return allocated_chunks_;
      }

      inline std::size_t
      memory_resource::free_chunks (void)
      {
        return free_chunks_;
      }

      inline std::size_t
      memory_resource::allocations (void)
      {
        return allocations_;
      }

      inline std::size_t
      memory_resource::deallocations (void)
      {
        return deallocations_;
      }

      inline void
      memory_resource::trace_print_statistics (void)
      {
#if defined(TRACE)
        trace::printf ("Memory '%s' @%p: \n"
                       "\ttotal: %u bytes, \n"
                       "\tallocated: %u bytes in %u chunk(s), \n"
                       "\tfree: %u bytes in %u chunk(s), \n"
                       "\tmax: %u bytes, \n"
                       "\tcalls: %u allocs, %u deallocs\n",
                       name (), this, total_bytes (), allocated_bytes (),
                       allocated_chunks (), free_bytes (), free_chunks (),
                       max_allocated_bytes (), allocations (),
                       deallocations ());
#endif /* defined(TRACE) */
      }

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

      inline bool
      operator== (memory_resource const & lhs, memory_resource const & rhs) noexcept
      {
        return &lhs == &rhs || lhs.is_equal (rhs);
      }

      inline bool
      operator!= (memory_resource const & lhs, memory_resource const & rhs) noexcept
      {
        return !(lhs == rhs);
      }

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

      template<typename T>
        template<typename U>
          inline
          allocator_stateless_default_resource<T>::allocator_stateless_default_resource (
              allocator_stateless_default_resource<U> const & other __attribute__((unused))) noexcept
          {
            ;
          }

      template<typename T>
        inline typename allocator_stateless_default_resource<T>::value_type*
        allocator_stateless_default_resource<T>::allocate (std::size_t elements)
        {
          scheduler::critical_section scs;

          return static_cast<value_type*> (get_default_resource ()->allocate (
              elements * sizeof(value_type)));
        }

      template<typename T>
        inline void
        allocator_stateless_default_resource<T>::deallocate (
            value_type* addr, std::size_t elements) noexcept
        {
          scheduler::critical_section scs;

          get_default_resource ()->deallocate (addr,
                                               elements * sizeof(value_type));
        }

      template<typename T>
        inline std::size_t
        allocator_stateless_default_resource<T>::max_size (void) const noexcept
        {
          return get_default_resource ()->max_size () / sizeof(value_type);
        }

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

      template<typename T, typename U, typename L, F get_resource>
        inline bool
        operator== (
            allocator_stateless_polymorphic_synchronized<T, L, get_resource> const & lhs,
            allocator_stateless_polymorphic_synchronized<U, L, get_resource> const & rhs) noexcept
        {
          return *lhs.resource () == *rhs.resource ();
        }

      template<typename T, typename U, typename L, F get_resource>
        inline bool
        operator!= (
            allocator_stateless_polymorphic_synchronized<T, L, get_resource> const & lhs,
            allocator_stateless_polymorphic_synchronized<U, L, get_resource> const & rhs) noexcept
        {
          return !(lhs == rhs);
        }

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

      template<typename T, typename L, F get_resource>
        inline
        allocator_stateless_polymorphic_synchronized<T, L, get_resource>::allocator_stateless_polymorphic_synchronized () noexcept
        {
          trace::printf ("%s() @%p %p\n", __func__, this, get_resource ());
        }

      template<typename T, typename L, F get_resource>
        template<typename U>
          inline
          allocator_stateless_polymorphic_synchronized<T, L, get_resource>::allocator_stateless_polymorphic_synchronized (
              allocator_stateless_polymorphic_synchronized<U, L, get_resource> const & other __attribute__((unused))) noexcept
          {
            ;
          }

      template<typename T, typename L, F get_resource>
        typename allocator_stateless_polymorphic_synchronized<T, L, get_resource>::value_type*
        allocator_stateless_polymorphic_synchronized<T, L, get_resource>::allocate (
            std::size_t elements)
        {
          trace::printf ("%s(%u) @%p\n", __func__, elements, this);

#if 0
          std::size_t ms = max_size ();
          if ((ms > 0) && (elements > max_size ()))
            {
              estd::__throw_system_error (
                  EINVAL,
                  "allocator_stateless_polymorphic_synchronized<T>::allocate(size_t n)"
                  " 'n' exceeds maximum supported size");
            }
#endif

          locker_type lk;
          std::lock_guard<locker_type> ulk
            { lk };

          return static_cast<value_type*> (get_resource ()->allocate (
              elements * sizeof(value_type), alignof(value_type)));
        }

      template<typename T, typename L, F get_resource>
        void
        allocator_stateless_polymorphic_synchronized<T, L, get_resource>::deallocate (
            value_type* addr, std::size_t elements) noexcept
        {
          trace::printf ("%s(%p,%u) @%p\n", __func__, addr, elements, this);

#if 0
          std::size_t ms = max_size ();
          if (ms > 0)
            {
              assert (elements <= max_size ());
            }
#endif

          locker_type lk;
          std::lock_guard<locker_type> ulk
            { lk };

          get_resource ()->deallocate (addr, elements * sizeof(value_type),
                                       alignof(value_type));
        }

      template<typename T, typename L, F get_resource>
        inline std::size_t
        allocator_stateless_polymorphic_synchronized<T, L, get_resource>::max_size (
            void) const noexcept
        {
          return get_resource ()->max_size () / sizeof(T);
        }

#if 0
      template<typename T, typename L, F get_resource>
      inline allocator_stateless_polymorphic_synchronized<T, L, get_resource>
      allocator_stateless_polymorphic_synchronized<T, L, get_resource>::select_on_container_copy_construction (
          void) const noexcept
        {
          return allocator_stateless_polymorphic_synchronized ();
        }

      template<typename T, typename L, F get_resource>
      inline memory_resource*
      allocator_stateless_polymorphic_synchronized<T, L, get_resource>::resource (
          void) const noexcept
        {
          return get_resource ();
        }
#endif

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

      template<typename A>
        inline
        allocator_deleter<A>::allocator_deleter ()
        {
          ;
        }

      template<typename A>
        inline
        allocator_deleter<A>::allocator_deleter (const allocator_type& other) :
            a_
              { other }
        {
          ;
        }

      template<typename A>
        inline void
        allocator_deleter<A>::operator() (pointer addr) const
        {
          // Local allocator, without it many errors are issued.
          // TODO: understand exactly why.
          allocator_type alloc
            { a_ };

          // Call the object destructor.
          allocator_traits::destroy (alloc, std::addressof (*addr));

          // Deallocate the object, using the same allocator
          // used to allocate the object.
          allocator_traits::deallocate (alloc, addr, 1);
        }

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

      template<typename T, typename A, typename ... Args>
        auto
        allocate_unique (const A& allocator, Args&&... args)
        {
          using allocator_type = A;

          using allocator_traits = std::allocator_traits<A>;

          static_assert(std::is_same<typename allocator_traits::value_type, std::remove_cv_t<T>>::value
              || std::is_base_of<typename allocator_traits::value_type, std::remove_cv_t<T>>::value,
              "Allocator must be of same type or derived.");

          static_assert(sizeof(T) <= sizeof(typename allocator_traits::value_type),
              "Derived type must not be larger.");

          allocator_type alloc
            { allocator };

          // Allocate space for 1 object instance of type T.
          auto p = allocator_traits::allocate (alloc, 1);

#if defined(__EXCEPTIONS)

          try
            {
              // Use placement new to construct the object.
              allocator_traits::construct (alloc, std::addressof (*p),
                  std::forward<Args>(args)...);

              // Figure out the deleter type.
              using D = allocator_deleter<A>;

              // Make the unique pointer with the object and the deleter.
              return std::unique_ptr<T, D> (p, D (alloc));
            }
          catch (...)
            {
              allocator_traits::deallocate (alloc, p, 1);
              throw;
            }

#else

          // Use placement new to construct the object.
          allocator_traits::construct (alloc, std::addressof (*p),
                                       std::forward<Args>(args)...);

          // Figure out the deleter type.
          using D = allocator_deleter<A>;

          // Make the unique pointer with the object and the deleter.
          return std::unique_ptr<T, D> (p, D (alloc));

#endif /* defined(__EXCEPTIONS) */
        }

    // ------------------------------------------------------------------------
    } /* namespace memory */
  } /* namespace rtos */
} /* namespace os */

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

#endif /* __cplusplus */

#endif /* CMSIS_PLUS_RTOS_OS_MEMORY_H_ */