le_mem.h

Go to the documentation of this file.

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

#ifndef LEGATO_MEM_INCLUDE_GUARD
#define LEGATO_MEM_INCLUDE_GUARD

#include "le_singlyLinkedList.h"

#ifndef LE_COMPONENT_NAME
#   define LE_COMPONENT_NAME
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef void (*le_mem_Destructor_t)
(
    void* objPtr    
);

// Max memory pool name bytes -- must match definition in limit.h
#define LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES 32

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_mem_Pool
{
    le_dls_Link_t poolLink;             
    struct le_mem_Pool* superPoolPtr;   
#if LE_CONFIG_MEM_POOL_STATS
    // These members go before LE_CONFIG_MEM_POOLS so numAllocations will always be aligned, even on
    // 32-bit architectures, even when LE_CONFIG_MEM_POOLS is not declared
    size_t numOverflows;                
    uint64_t numAllocations;            
    size_t maxNumBlocksUsed;            
#endif
#if LE_CONFIG_MEM_POOLS
    le_sls_List_t freeList;             
#endif

    size_t userDataSize;                
    size_t blockSize;                   
    size_t totalBlocks;                 
    size_t numBlocksInUse;              
    size_t numBlocksToForce;            
#if LE_CONFIG_MEM_TRACE
    le_log_TraceRef_t memTrace;         
#endif

    le_mem_Destructor_t destructor;     
#if LE_CONFIG_MEM_POOL_NAMES_ENABLED
    char name[LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES]; 
#endif
}
le_mem_Pool_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_mem_Pool* le_mem_PoolRef_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct
{
    size_t      numBlocksInUse;     
    size_t      maxNumBlocksUsed;   
    size_t      numOverflows;       
    uint64_t    numAllocs;          
    size_t      numFree;            
}
le_mem_PoolStats_t;


#if LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    le_mem_PoolRef_t _le_mem_GetBlockPool
    (
        void*   objPtr  
    );

    typedef void* (*_le_mem_AllocFunc_t)(le_mem_PoolRef_t pool);

    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* _le_mem_AllocTracer
    (
        le_mem_PoolRef_t     pool,             
        _le_mem_AllocFunc_t  funcPtr,          
        const char*          poolFunction,     
        const char*          file,             
        const char*          callingfunction,  
        size_t               line              
    );

    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* _le_mem_VarAllocTracer
    (
        le_mem_PoolRef_t     pool,             
        size_t               size,             
        _le_mem_AllocFunc_t  funcPtr,          
        const char*          poolFunction,     
        const char*          file,             
        const char*          callingfunction,  
        size_t               line              
    );

    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void _le_mem_Trace
    (
        le_mem_PoolRef_t    pool,             
        const char*         file,             
        const char*         callingfunction,  
        size_t              line,             
        const char*         poolFunction,     
        void*               blockPtr          
    );
#endif


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_InitStaticPool
(
    const char* componentName,  
    const char* name,           
    size_t      numBlocks,      
    size_t      objSize, 
    le_mem_Pool_t* poolPtr, 
    void* poolDataPtr       
);


#if LE_CONFIG_MEM_POOL_NAMES_ENABLED
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_CreatePool
(
    const char* componentName,  
    const char* name,           
    size_t      objSize         
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
static inline le_mem_PoolRef_t le_mem_CreatePool
(
    const char* name,           
    size_t      objSize         
)
{
    return _le_mem_CreatePool(STRINGIZE(LE_COMPONENT_NAME), name, objSize);
}
#else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_CreatePool
(
    size_t      objSize         
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreatePool
(
    const char* name,           
    size_t      objSize         
)
{
    return _le_mem_CreatePool(objSize);
}
#endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#define LE_MEM_POOL_WORDS(numBlocks, objSize)                           \
    ((numBlocks)*(((sizeof(le_mem_Pool_t*) + sizeof(size_t)) /* sizeof(MemBlock_t) */ + \
                   (((objSize)<sizeof(le_sls_Link_t))?sizeof(le_sls_Link_t):(objSize))+ \
                   sizeof(uint32_t)*LE_CONFIG_NUM_GUARD_BAND_WORDS*2+      \
                   sizeof(size_t) - 1) / sizeof(size_t)))

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#define LE_MEM_BLOCKS(name, def) (LE_DEFAULT(CAT(_mem_, CAT(name, _POOL_SIZE)), (def)))

//--------------------------------------------------------------------------------------------------
/*
 * Internal Note: size_t is used instead of uint8_t to ensure alignment on platforms where
 * alignment matters.
 */
//--------------------------------------------------------------------------------------------------
#if LE_CONFIG_MEM_POOLS
#  define LE_MEM_DEFINE_STATIC_POOL(name, numBlocks, objSize)   \
    static le_mem_Pool_t _mem_##name##Pool;                     \
    static size_t _mem_##name##Data[LE_MEM_POOL_WORDS(LE_MEM_BLOCKS(name, numBlocks), objSize)]
#else
#  define LE_MEM_DEFINE_STATIC_POOL(name, numBlocks, objSize)   \
    static le_mem_Pool_t _mem_##name##Pool
#endif

//--------------------------------------------------------------------------------------------------
/*
 * Internal Note: size_t is used instead of uint8_t to ensure alignment on platforms where
 * alignment matters.
 */
//--------------------------------------------------------------------------------------------------
#if LE_CONFIG_MEM_POOLS
#  define LE_MEM_DEFINE_STATIC_POOL_IN_SECTION(name, numBlocks, objSize, sectionName)    \
    static le_mem_Pool_t _mem_##name##Pool __attribute__((section(sectionName)));        \
    static size_t _mem_##name##Data[LE_MEM_POOL_WORDS(                                   \
        LE_MEM_BLOCKS(name, numBlocks), objSize)] __attribute__((section(sectionName)))
#else
#  define LE_MEM_DEFINE_STATIC_POOL_IN_SECTION(name, numBlocks, objSize, sectionName)    \
    static le_mem_Pool_t _mem_##name##Pool __attribute__((section(sectionName)));
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#if LE_CONFIG_MEM_POOLS
#  define le_mem_InitStaticPool(name, numBlocks, objSize)                               \
    (inline_static_assert(                                                              \
        sizeof(_mem_##name##Data) ==                                                    \
            sizeof(size_t[LE_MEM_POOL_WORDS(LE_MEM_BLOCKS(name, numBlocks), objSize)]), \
        "initial pool size does not match definition"),                                 \
    _le_mem_InitStaticPool(STRINGIZE(LE_COMPONENT_NAME), #name,                         \
        LE_MEM_BLOCKS(name, numBlocks), (objSize), &_mem_##name##Pool, _mem_##name##Data))
#else
#  define le_mem_InitStaticPool(name, numBlocks, objSize)       \
    _le_mem_InitStaticPool(STRINGIZE(LE_COMPONENT_NAME), #name, \
        LE_MEM_BLOCKS(name, numBlocks), (objSize), &_mem_##name##Pool, NULL)
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t le_mem_ExpandPool
(
    le_mem_PoolRef_t    pool,       
    size_t              numObjects  
);



#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* le_mem_TryAlloc
    (
        le_mem_PoolRef_t    pool    
    );
#else
    void* _le_mem_TryAlloc(le_mem_PoolRef_t pool);

#   define le_mem_TryAlloc(pool)                                                                    \
        _le_mem_AllocTracer(pool,                                                                   \
                            _le_mem_TryAlloc,                                                       \
                            "le_mem_TryAlloc",                                                      \
                            STRINGIZE(LE_FILENAME),                                                 \
                            __FUNCTION__,                                                           \
                            __LINE__)

#endif


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* le_mem_AssertAlloc
    (
        le_mem_PoolRef_t    pool    
    );
#else
    void* _le_mem_AssertAlloc(le_mem_PoolRef_t pool);

#   define le_mem_AssertAlloc(pool)                                                                 \
        _le_mem_AllocTracer(pool,                                                                   \
                            _le_mem_AssertAlloc,                                                    \
                            "le_mem_AssertAlloc",                                                   \
                            STRINGIZE(LE_FILENAME),                                                 \
                            __FUNCTION__,                                                           \
                            __LINE__)
#endif


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* le_mem_ForceAlloc
    (
        le_mem_PoolRef_t    pool    
    );
#else
    void* _le_mem_ForceAlloc(le_mem_PoolRef_t pool);

#   define le_mem_ForceAlloc(pool)                                                                  \
        _le_mem_AllocTracer(pool,                                                                   \
                            _le_mem_ForceAlloc,                                                     \
                            "le_mem_ForceAlloc",                                                    \
                            STRINGIZE(LE_FILENAME),                                                 \
                            __FUNCTION__,                                                           \
                            __LINE__)
#endif


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* le_mem_TryVarAlloc
    (
        le_mem_PoolRef_t    pool,         
        size_t              size          
    );
#else
    void* _le_mem_TryVarAlloc(le_mem_PoolRef_t pool, size_t size);

#   define le_mem_TryVarAlloc(pool, size)                               \
         _le_mem_VarAllocTracer(pool,                                   \
                                size,                                   \
                                _le_mem_TryVarAlloc,                    \
                                "le_mem_TryVarAlloc",                   \
                                STRINGIZE(LE_FILENAME),                 \
                                __FUNCTION__,                           \
                                __LINE__)

#endif


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* le_mem_AssertVarAlloc
    (
        le_mem_PoolRef_t    pool,        
        size_t              size         
    );
#else
    void* _le_mem_AssertVarAlloc(le_mem_PoolRef_t pool, size_t size);

#   define le_mem_AssertVarAlloc(pool, size)                            \
        _le_mem_VarAllocTracer(pool,                                    \
                               size,                                    \
                               _le_mem_AssertVarAlloc,                  \
                               "le_mem_AssertVarAlloc",                 \
                               STRINGIZE(LE_FILENAME),                  \
                               __FUNCTION__,                            \
                               __LINE__)
#endif


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void* le_mem_ForceVarAlloc
    (
        le_mem_PoolRef_t    pool,        
        size_t              size         
    );
#else
    void* _le_mem_ForceVarAlloc(le_mem_PoolRef_t pool, size_t size);

#   define le_mem_ForceVarAlloc(pool, size)                             \
        _le_mem_VarAllocTracer(pool,                                    \
                               size,                                    \
                               _le_mem_ForceVarAlloc,                   \
                               "le_mem_ForceVarAlloc",                  \
                               STRINGIZE(LE_FILENAME),                  \
                               __FUNCTION__,                            \
                               __LINE__)
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#if LE_CONFIG_MEM_ALLOC_FORCE
#   define le_mem_Alloc(pool)   le_mem_ForceAlloc(pool)
#elif LE_CONFIG_MEM_ALLOC_ASSERT
#   define le_mem_Alloc(pool)   le_mem_AssertAlloc(pool)
#else
#   error "No supported allocation scheme selected!"
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#if LE_CONFIG_MEM_ALLOC_FORCE
#   define le_mem_VarAlloc(pool, size)  le_mem_ForceVarAlloc((pool), (size))
#elif LE_CONFIG_MEM_ALLOC_ASSERT
#   define le_mem_VarAlloc(pool, size)  le_mem_AssertVarAlloc((pool), (size))
#else
#   error "No supported allocation scheme selected!"
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_SetNumObjsToForce
(
    le_mem_PoolRef_t    pool,       
    size_t              numObjects  
);


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void le_mem_Release
    (
        void*   objPtr  
    );
#else
    void _le_mem_Release(void* objPtr);

#   define le_mem_Release(objPtr)                                                                   \
            _le_mem_Trace(_le_mem_GetBlockPool(objPtr),                                             \
                          STRINGIZE(LE_FILENAME),                                                   \
                          __FUNCTION__,                                                             \
                          __LINE__,                                                                 \
                          "le_mem_Release",                                                         \
                          (objPtr));                                                                \
            _le_mem_Release(objPtr);
#endif


#if !LE_CONFIG_MEM_TRACE
    //----------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------
    void le_mem_AddRef
    (
        void*   objPtr  
    );
#else
    void _le_mem_AddRef(void* objPtr);

#   define le_mem_AddRef(objPtr)                                                                    \
        _le_mem_Trace(_le_mem_GetBlockPool(objPtr),                                                 \
                      STRINGIZE(LE_FILENAME),                                                       \
                      __FUNCTION__,                                                                 \
                      __LINE__,                                                                     \
                      "le_mem_AddRef",                                                              \
                      (objPtr));                                                                    \
        _le_mem_AddRef(objPtr);
#endif

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
size_t le_mem_GetBlockSize
(
    void* objPtr                 
);

//----------------------------------------------------------------------------------------------
//----------------------------------------------------------------------------------------------
size_t le_mem_GetRefCount
(
    void*   objPtr  
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_SetDestructor
(
    le_mem_PoolRef_t    pool,       
    le_mem_Destructor_t destructor  
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_GetStats
(
    le_mem_PoolRef_t    pool,       
    le_mem_PoolStats_t* statsPtr    
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_ResetStats
(
    le_mem_PoolRef_t    pool        
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_result_t le_mem_GetName
(
    le_mem_PoolRef_t    pool,       
    char*               namePtr,    
    size_t              bufSize     
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
bool le_mem_IsSubPool
(
    le_mem_PoolRef_t    pool        
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
size_t le_mem_GetObjectCount
(
    le_mem_PoolRef_t    pool        
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
size_t le_mem_GetObjectSize
(
    le_mem_PoolRef_t    pool        
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
size_t le_mem_GetObjectFullSize
(
    le_mem_PoolRef_t    pool        
);


#if LE_CONFIG_MEM_POOL_NAMES_ENABLED
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_FindPool
(
    const char* componentName,  
    const char* name            
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
static inline le_mem_PoolRef_t le_mem_FindPool
(
    const char* name            
)
{
    return _le_mem_FindPool(STRINGIZE(LE_COMPONENT_NAME), name);
}
#else
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_FindPool
(
    const char* name            
)
{
    return NULL;
}
#endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */


#if LE_CONFIG_MEM_POOL_NAMES_ENABLED
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_CreateSubPool
(
    le_mem_PoolRef_t    superPool,  
    const char*         componentName,  
    const char*         name,       
    size_t              numObjects  
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
static inline le_mem_PoolRef_t le_mem_CreateSubPool
(
    le_mem_PoolRef_t    superPool,      
    const char*         name,           
    size_t              numObjects      
)
{
    return _le_mem_CreateSubPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects);
}
#else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_CreateSubPool
(
    le_mem_PoolRef_t    superPool,      
    size_t              numObjects      
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreateSubPool
(
    le_mem_PoolRef_t    superPool,      
    const char*         name,           
    size_t              numObjects      
)
{
    return _le_mem_CreateSubPool(superPool, numObjects);
}
#endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */


#if LE_CONFIG_MEM_POOL_NAMES_ENABLED
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_CreateReducedPool
(
    le_mem_PoolRef_t    superPool,      
    const char*         componentName,  
    const char*         name,           
    size_t              numObjects,     
    size_t              objSize         
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
static inline le_mem_PoolRef_t le_mem_CreateReducedPool
(
    le_mem_PoolRef_t    superPool,      
    const char*         name,           
    size_t              numObjects,     
    size_t              objSize         
)
{
    return _le_mem_CreateReducedPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects, objSize);
}
#else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_mem_PoolRef_t _le_mem_CreateReducedPool
(
    le_mem_PoolRef_t    superPool,      
    size_t              numObjects,     
    size_t              objSize         
);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreateReducedPool
(
    le_mem_PoolRef_t    superPool,      
    const char*         name,           
    size_t              numObjects,     
    size_t              objSize         
)
{
    return _le_mem_CreateReducedPool(superPool, numObjects, objSize);
}
#endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_DeleteSubPool
(
    le_mem_PoolRef_t    subPool     
);

#if LE_CONFIG_RTOS
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_Hibernate
(
    void **freeStartPtr,     
    void **freeEndPtr        
);

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_mem_Resume
(
    void
);

#endif /* end LE_CONFIG_RTOS */

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
char *le_mem_StrDup
(
    le_mem_PoolRef_t     poolRef,   
    const char          *srcStr     
);

#endif // LEGATO_MEM_INCLUDE_GUARD