MuditaOS/module-os/RTOSWrapper/include/mem_pool.hpp

/****************************************************************************
 *
 *  Copyright (c) 2017, Michael Becker (michael.f.becker@gmail.com)
 *
 *  This file is part of the FreeRTOS Add-ons project.
 *
 *  Source Code:
 *  https://github.com/michaelbecker/freertos-addons
 *
 *  Project Page:
 *  http://michaelbecker.github.io/freertos-addons/
 *
 *  On-line Documentation:
 *  http://michaelbecker.github.io/freertos-addons/docs/html/index.html
 *
 *  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.
 *  + Credit is appreciated, but not required, if you find this project
 *    useful enough to include in your application, product, device, etc.
 *
 *  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 MEM_POOL_HPP_
#define MEM_POOL_HPP_

/**
 *  C++ exceptions are used by default when constructors fail.
 *  If you do not want this behavior, define the following in your makefile
 *  or project. Note that in most / all cases when a constructor fails,
 *  it's a fatal error. In the cases when you've defined this, the new
 *  default behavior will be to issue a configASSERT() instead.
 */
#ifndef CPP_FREERTOS_NO_EXCEPTIONS
#include <exception>
#include <string>
#include <cstdio>
#ifdef CPP_FREERTOS_NO_CPP_STRINGS
#error "FreeRTOS-Addons require C++ Strings if you are using exceptions"
#endif
#endif
#include <list>
#include "FreeRTOS.h"
#include "mutex.hpp"

namespace cpp_freertos {


#ifndef CPP_FREERTOS_NO_EXCEPTIONS
/**
 *  This is the exception that is thrown if a MemoryPool malloc fails.
 */
class MemoryPoolMallocException : public std::exception {

    public:
        /**
         *  Create the exception.
         */
        MemoryPoolMallocException()
        {
            sprintf(errorString, "MemoryPool malloc Failed");
        }

        /**
         *  Get what happened as a string.
         *  We are overriding the base implementation here.
         */
        virtual const char *what() const throw()
        {
            return errorString;
        }

    private:
        /**
         *  A text string representing what failed.
         */
        char errorString[80];
};

/**
 *  This is the exception that is thrown if the Alignment argument
 *  is invalid.
 */
class MemoryPoolBadAlignmentException : public std::exception {

    public:
        /**
         *  Create the exception.
         */
        MemoryPoolBadAlignmentException()
        {
            sprintf(errorString, "MemoryPool Bad Alignment");
        }

        /**
         *  Get what happened as a string.
         *  We are overriding the base implementation here.
         */
        virtual const char *what() const throw()
        {
            return errorString;
        }

    private:
        /**
         *  A text string representing what failed.
         */
        char errorString[80];
};

#endif


/**
 *  Memory Pools are fixed size allocations to prevent fragmentation.
 *
 *  This is a new feature to FreeRTOS Wrappers and is not in and of
 *  itself a wrapper.
 *
 *  Memory Pools are thread safe, but cannot be used in ISR context.
 *  The OS must be running, because these use Mutexes to protect internal
 *  data structures.
 */
class MemoryPool {

    /////////////////////////////////////////////////////////////////////////
    //
    //  Public API
    //
    /////////////////////////////////////////////////////////////////////////
    public:

        /**
         *  Constructor to create a Memory Pool.
         *
         *  This constructor uses the system malloc to actually obtain
         *  the memory.
         *
         *  @param itemSize How big is each item you want to allocate.
         *  @param itemCount How many items max do you want to allocate
         *      at once.
         *  @param Alignment Power of 2 value denoting on which address boundary the
         *      memory will be aligned to. Must be at least sizeof(unsigned char *).
         *  @throws MemoryPoolMallocException on failure.
         *  @throws MemoryPoolBadAlignmentException on failure.
         */
        MemoryPool( int itemSize,
                    int itemCount,
                    int alignment);

        /**
         *  Constructor to create a Memory Pool.
         *
         *  This constructor uses memory you pass in to actually create
         *  the pool. This constructor does not throw.
         *
         *  @param itemSize How big is each item you want to allocate.
         *  @param preallocatedMemory Pointer to the preallocated memory
         *  you are dedicating to this pool.
         *  @param preallocatedMemorySize How big is the buffer you are
         *  passing in.
         *  @param Alignment Power of 2 value denoting on which address boundary the
         *      memory will be aligned to. Must be at least sizeof(unsigned char *).
         *  @throws MemoryPoolBadAlignmentException on failure.
         */
        MemoryPool( int itemSize,
                    void *preallocatedMemory,
                    int preallocatedMemorySize,
                    int alignment);

        /**
         *  Allows you to add memory to a MemoryPool.
         *
         *  Items will be the same size as you initially asked for.
         *
         *  @param itemCount How many more items max do you want to allocate
         *  @throws MemoryPoolMallocException on failure.
         */
        void AddMemory(int itemCount);

        /**
         *  Allows you to add memory to a MemoryPool.
         *
         *  Items will be the same size as you initially asked for.
         *
         *  @param preallocatedMemory Pointer to the preallocated memory
         *  you are dedicating to this pool.
         *  @param preallocatedMemorySize How big is the buffer you are
         *  passing in.
         */
        void AddMemory( void *preallocatedMemory,
                        int preallocatedMemorySize);

        /**
         *  Allocate an item from the pool.
         *
         *  @return Pointer of the memory or NULL if the pool is empty.
         */
        void *Allocate();

        /**
         *  Returns the item back to it's pool.
         *
         *  @note There is no checking that the item is actually
         *  valid to be returned to this pool.
         */
        void Free(void *item);

    /////////////////////////////////////////////////////////////////////////
    //
    //  Private API
    //  The internals of this class.
    //
    /////////////////////////////////////////////////////////////////////////
    private:

        /**
         *  Standard Mutex to allow thread safety.
         */
        Mutex *Lock;

        /**
         *  Save the item size for additions.
         */
        int ItemSize;

        /**
         *  The overall alignment of an item.
         */
        int Alignment;

        /**
         *  All of the real work is done with STL lists.
         */
        std::list<void *>FreeItems;

        /**
         *  Adjusts and validates the alignment argument
         *  passed in the ctor.
         */
        void CalculateValidAlignment();

        /**
         *  Calculate the true item size, based on alignment.
         */
        void CalculateItemSize();

//
//  If we are using C++11 or later, take advantage of the
//  newer features to find bugs.
//
#if __cplusplus >= 201103L
        /**
         *  To correctly delete a Memory Pool, we'd have to guarantee that
         *  all allocations had been returned to us. We side step this issue
         *  as well as all the associated overhead with supporting this by
         *  not allowing destructors.
         */
        ~MemoryPool() = delete;
#else
        /**
         *  To correctly delete a Memory Pool, we'd have to guarantee that
         *  all allocations had been returned to us. We side step this issue
         *  by making the destructor private so it can't be accessed.
         */
        ~MemoryPool();
#endif


};


}

#endif