legato_variableheap.h

Go to the documentation of this file.

/*******************************************************************************
* Copyright (C) 2020 Microchip Technology Inc. and its subsidiaries.
*
* Subject to your compliance with these terms, you may use Microchip software
* and any derivatives exclusively with Microchip products. It is your
* responsibility to comply with third party license terms applicable to your
* use of third party software (including open source software) that may
* accompany Microchip software.
*
* THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER
* EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED
* WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A
* PARTICULAR PURPOSE.
*
* IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE,
* INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND
* WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS
* BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE
* FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN
* ANY WAY RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
* THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
*******************************************************************************/
#ifndef LEGATO_VARIABLEHEAP_H
#define LEGATO_VARIABLEHEAP_H

#include "gfx/legato/common/legato_common.h"

#if LE_MEMORY_MANAGER_ENABLE == 1

#if LE_USE_DEBUG_ALLOCATOR == 1
#define LE_VHEAP_ALLOC(heap, size) leVariableHeap_Alloc(heap, size, __LINE__, __FUNCTION__, __FILE__)
#define LE_VHEAP_REALLOC(heap, ptr, size) leVariableHeap_Realloc(heap, ptr, size, __LINE__, __FUNCTION__, __FILE__)
#else
#define LE_VHEAP_ALLOC(heap, size) leVariableHeap_Alloc(heap, size)
#define LE_VHEAP_REALLOC(heap, ptr, size) leVariableHeap_Realloc(ptr, size)
#endif

// *****************************************************************************
/* Structure:
    struct leVariableHeap

  Summary:
    Defines a variable heap object.  A variable heap is an allocator is
    capable of allocating blocks of a variable size.  This heap is flexible
    in capability but suffers from fragmentation and possibly slower allocation
    times than a fixed heap.  Good for larger allocation sizes.

    leBool initialized - indicates whether the heap has been properly initialized
    size_t size - the overall size of the heap
    size_t used - the amount of space the heap is currently using
    size_t maxUsage - the highest amount of usage the heap has seen
    void* data - pointer to the heap data
    void* allocList - a linked list of allocation data blocks
    void* freeList - a linked list of free data blocks
    size_t allocBlockCount - the number of blocks currently allocated
    size_t freeBlockCount - the number of blocks in the free list
*/
typedef struct leVariableHeap
{
    leBool initialized;
    size_t size;
    size_t used;
    size_t maxUsage;

    void* data;

    void* allocList;
    void* freeList;

    size_t allocBlockCount;
    size_t freeBlockCount;
} leVariableHeap;

// *****************************************************************************
leResult leVariableHeap_Init(leVariableHeap* heap,
                             void* data,
                             size_t size);

// *****************************************************************************
void leVariableHeap_Destroy(leVariableHeap* heap);

#if LE_USE_DEBUG_ALLOCATOR == 1
// *****************************************************************************
/* Function:
    void* leVariableHeap_Alloc(leVariableHeap* heap,
                               size_t size,
                               size_t lineNum,
                               const char* funcName,
                               const char* fileName)

  Summary:
    Allocates a block from a variable heap.

  Description:
    Allocates a block from a variable heap.  This is the debug version of this
    function and requires additional parameters.

    Use the LE_MALLOC macro to automatically differentiate between
    this function and its non-debug counterpart.

  Parameters:
    leVariableHeap* heap - pointer to the heap object
    size_t size - the size
    size_t lineNum - the file line number where this allocation occured
    const char* funcName - the function name where this allocation occured
    const char* fileName - the file name where this allocation occured

  Returns:
    leResult
*/
void* leVariableHeap_Alloc(leVariableHeap* heap,
                           size_t size,
                           size_t lineNum,
                           const char* funcName,
                           const char* fileName);
#else
// *****************************************************************************
void* leVariableHeap_Alloc(leVariableHeap* heap,
                           size_t size);
#endif

#if LE_USE_DEBUG_ALLOCATOR == 1

void* leVariableHeap_Realloc(leVariableHeap* heap,
                             void* ptr,
                             size_t size,
                             size_t lineNum,
                             const char* funcName,
                             const char* fileName);

#else

void* leVariableHeap_Realloc(leVariableHeap* heap,
                             void* ptr,
                             size_t size);
#endif
// *****************************************************************************
void leVariableHeap_Free(leVariableHeap* heap,
                         void* ptr);

// *****************************************************************************
leBool leVariableHeap_Contains(leVariableHeap* heap,
                               void* ptr);

// *****************************************************************************
leResult leVariableHeap_Validate(leVariableHeap* heap);

// *****************************************************************************
size_t leVariableHeap_SizeOf(leVariableHeap* heap,
                             void* ptr);

// *****************************************************************************

void leVariableHeap_Dump(leVariableHeap* heap,
                         leBool dumpRecords);

#endif // LE_MEMORY_MANAGER_ENABLE

#endif /* LEGATO_VARIABLEHEAP_H */