le_mem.h File Reference

Go to the source code of this file.

Data Structures

struct  le_mem_Pool_t
 
struct  le_mem_PoolStats_t
 

Macros

#define LE_COMPONENT_NAME
 
#define LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES   32
 

Typedefs

typedef void(* le_mem_Destructor_t) (void *objPtr)
 
typedef struct le_mem_Pool * le_mem_PoolRef_t
 

Functions

static le_mem_PoolRef_t le_mem_CreatePool (const char *name, size_t objSize)
 
le_mem_PoolRef_t le_mem_ExpandPool (le_mem_PoolRef_t pool, size_t numObjects)
 
void * le_mem_TryAlloc (le_mem_PoolRef_t pool)
 
void * le_mem_AssertAlloc (le_mem_PoolRef_t pool)
 
void * le_mem_ForceAlloc (le_mem_PoolRef_t pool)
 
void * le_mem_TryVarAlloc (le_mem_PoolRef_t pool, size_t size)
 
void * le_mem_AssertVarAlloc (le_mem_PoolRef_t pool, size_t size)
 
void * le_mem_ForceVarAlloc (le_mem_PoolRef_t pool, size_t size)
 
void le_mem_SetNumObjsToForce (le_mem_PoolRef_t pool, size_t numObjects)
 
void le_mem_Release (void *objPtr)
 
void le_mem_AddRef (void *objPtr)
 
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)
 
static le_mem_PoolRef_t le_mem_FindPool (const char *name)
 
static le_mem_PoolRef_t le_mem_CreateSubPool (le_mem_PoolRef_t superPool, const char *name, size_t numObjects)
 
static le_mem_PoolRef_t le_mem_CreateReducedPool (le_mem_PoolRef_t superPool, const char *name, size_t numObjects, size_t objSize)
 
void le_mem_DeleteSubPool (le_mem_PoolRef_t subPool)
 
void le_mem_Hibernate (void **freeStartPtr, void **freeEndPtr)
 
void le_mem_Resume (void)
 
char * le_mem_StrDup (le_mem_PoolRef_t poolRef, const char *srcStr)
 

Detailed Description

Legato Dynamic Memory Allocation API include file.

Typedef Documentation

◆ le_mem_Destructor_t

typedef void(* le_mem_Destructor_t) (void *objPtr)

Prototype for destructor functions.

Parameters
objPtrPointer to the object where reference count has reached zero. After the destructor returns this object's memory will be released back into the pool (and this pointer will become invalid).
Returns
Nothing.

See Destructors for more information.

◆ le_mem_PoolRef_t

typedef struct le_mem_Pool* le_mem_PoolRef_t

Objects of this type are used to refer to a memory pool created using either le_mem_CreatePool() or le_mem_CreateSubPool().

Function Documentation

◆ le_mem_AddRef()

void le_mem_AddRef ( void *  objPtr)

Increments the reference count on an object by 1.

See Reference Counting for more information.

Returns
Nothing.
Parameters
[in]objPtrPointer to the object.

◆ le_mem_AssertAlloc()

void* le_mem_AssertAlloc ( le_mem_PoolRef_t  pool)

Allocates an object from a pool or logs a fatal error and terminates the process if the pool doesn't have any free objects to allocate.

Returns
Pointer to the allocated object.
Note
On failure, the process exits, so you don't have to worry about checking the returned pointer for validity.
Parameters
[in]poolPool from which the object is to be allocated.

◆ le_mem_AssertVarAlloc()

void* le_mem_AssertVarAlloc ( le_mem_PoolRef_t  pool,
size_t  size 
)

Allocates an object from a pool or logs a fatal error and terminates the process if the pool doesn't have any free objects to allocate.

Returns
Pointer to the allocated object.
Note
On failure, the process exits, so you don't have to worry about checking the returned pointer for validity.
Parameters
[in]poolPool from which the object is to be allocated.
[in]sizeThe size of block to allocate

◆ le_mem_CreatePool()

LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreatePool ( const char *  name,
size_t  objSize 
)
inlinestatic

Creates an empty memory pool.

Returns
Reference to the memory pool object.
Note
On failure, the process exits, so you don't have to worry about checking the returned reference for validity.
Parameters
[in]nameName of the pool inside the component.
[in]objSizeSize of the individual objects to be allocated from this pool (in bytes), e.g., sizeof(MyObject_t).

◆ le_mem_CreateReducedPool()

LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreateReducedPool ( le_mem_PoolRef_t  superPool,
const char *  name,
size_t  numObjects,
size_t  objSize 
)
inlinestatic

Creates a sub-pool of smaller objects.

See Reduced-size pools for more information.

Returns
Reference to the sub-pool.
Parameters
[in]superPoolSuper-pool.
[in]nameName of the sub-pool (will be copied into the sub-pool).
[in]numObjectsMinimum number of objects in the subpool by default.
[in]objSizeMinimum size of objects in the subpool.

◆ le_mem_CreateSubPool()

LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreateSubPool ( le_mem_PoolRef_t  superPool,
const char *  name,
size_t  numObjects 
)
inlinestatic

Creates a sub-pool.

See Sub-Pools for more information.

Returns
Reference to the sub-pool.
Parameters
[in]superPoolSuper-pool.
[in]nameName of the sub-pool (will be copied into the sub-pool).
[in]numObjectsNumber of objects to take from the super-pool.

◆ le_mem_DeleteSubPool()

void le_mem_DeleteSubPool ( le_mem_PoolRef_t  subPool)

Deletes a sub-pool.

See Sub-Pools for more information.

Returns
Nothing.
Parameters
[in]subPoolSub-pool to be deleted.

◆ le_mem_ExpandPool()

le_mem_PoolRef_t le_mem_ExpandPool ( le_mem_PoolRef_t  pool,
size_t  numObjects 
)

Expands the size of a memory pool.

Returns
Reference to the memory pool object (the same value passed into it).
Note
On failure, the process exits, so you don't have to worry about checking the returned reference for validity.
Parameters
[in]poolPool to be expanded.
[in]numObjectsNumber of objects to add to the pool.

◆ le_mem_FindPool()

LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_FindPool ( const char *  name)
inlinestatic

Finds a pool based on the pool's name.

Returns
Reference to the pool, or NULL if the pool doesn't exist.
Parameters
[in]nameName of the pool inside the component.

◆ le_mem_ForceAlloc()

void* le_mem_ForceAlloc ( le_mem_PoolRef_t  pool)

Allocates an object from a pool or logs a warning and expands the pool if the pool doesn't have any free objects to allocate.

Returns
Pointer to the allocated object.
Note
On failure, the process exits, so you don't have to worry about checking the returned pointer for validity.
Parameters
[in]poolPool from which the object is to be allocated.

◆ le_mem_ForceVarAlloc()

void* le_mem_ForceVarAlloc ( le_mem_PoolRef_t  pool,
size_t  size 
)

Allocates an object from a pool or logs a warning and expands the pool if the pool doesn't have any free objects to allocate.

Returns
Pointer to the allocated object.
Note
On failure, the process exits, so you don't have to worry about checking the returned pointer for validity.
Parameters
[in]poolPool from which the object is to be allocated.
[in]sizeThe size of block to allocate

◆ le_mem_GetBlockSize()

size_t le_mem_GetBlockSize ( void *  objPtr)

Fetches the size of a block (in bytes).

Returns
Object size, in bytes.
Parameters
[in]objPtrPointer to the object to get size of.

◆ le_mem_GetName()

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

Gets the memory pool's name, including the component name prefix.

If the pool were given the name "myPool" and the component that it belongs to is called "myComponent", then the full pool name returned by this function would be "myComponent.myPool".

Returns
LE_OK if successful. LE_OVERFLOW if the name was truncated to fit in the provided buffer.
Parameters
[in]poolThe memory pool.
[out]namePtrBuffer to store the name of the memory pool.
[in]bufSizeSize of the buffer namePtr points to.

◆ le_mem_GetObjectCount()

size_t le_mem_GetObjectCount ( le_mem_PoolRef_t  pool)

Fetches the number of objects a specified pool can hold (this includes both the number of free and in-use objects).

Returns
Total number of objects.
Parameters
[in]poolPool where number of objects is to be fetched.

◆ le_mem_GetObjectFullSize()

size_t le_mem_GetObjectFullSize ( le_mem_PoolRef_t  pool)

Fetches the total size of the object including all the memory overhead in a given pool (in bytes).

Returns
Total object memory size, in bytes.
Parameters
[in]poolThe pool whose object memory size is to be fetched.

◆ le_mem_GetObjectSize()

size_t le_mem_GetObjectSize ( le_mem_PoolRef_t  pool)

Fetches the size of the objects in a specified pool (in bytes).

Returns
Object size, in bytes.
Parameters
[in]poolPool where object size is to be fetched.

◆ le_mem_GetRefCount()

size_t le_mem_GetRefCount ( void *  objPtr)

Fetches the reference count on an object.

See Reference Counting for more information.

Warning
If using this in a multi-threaded application that shares memory pool objects between threads, steps must be taken to coordinate the threads (e.g., using a mutex) to ensure that the reference count value fetched remains correct when it is used.
Returns
The reference count on the object.
Parameters
[in]objPtrPointer to the object.

◆ le_mem_GetStats()

void le_mem_GetStats ( le_mem_PoolRef_t  pool,
le_mem_PoolStats_t statsPtr 
)

Fetches the statistics for a specified pool.

Returns
Nothing. Uses output parameter instead.
Parameters
[in]poolPool where stats are to be fetched.
[out]statsPtrPointer to where the stats will be stored.

◆ le_mem_Hibernate()

void le_mem_Hibernate ( void **  freeStartPtr,
void **  freeEndPtr 
)

Compress memory pools ready for hibernate-to-RAM

This compresses the memory pools ready for hibernation. All Legato tasks must remain suspended until after le_mem_Resume() is called.

Returns
Nothing
Parameters
[out]freeStartPtrBeginning of unused memory which does not need to be preserved in hibernation
[out]freeEndPtrEnd of unused memory

◆ le_mem_IsSubPool()

bool le_mem_IsSubPool ( le_mem_PoolRef_t  pool)

Checks if the specified pool is a sub-pool.

Returns
true if it is a sub-pool. false if it is not a sub-pool.
Parameters
[in]poolThe memory pool.

◆ le_mem_Release()

void le_mem_Release ( void *  objPtr)

Releases an object. If the object's reference count has reached zero, it will be destructed and its memory will be put back into the pool for later reuse.

Returns
Nothing.
Warning
  • Don't EVER access an object after releasing it. It might not exist anymore.
  • If the object has a destructor accessing a data structure shared by multiple threads, ensure you hold the mutex (or take other measures to prevent races) before releasing the object.
Parameters
[in]objPtrPointer to the object to be released.

◆ le_mem_ResetStats()

void le_mem_ResetStats ( le_mem_PoolRef_t  pool)

Resets the statistics for a specified pool.

Returns
Nothing.
Parameters
[in]poolPool where stats are to be reset.

◆ le_mem_Resume()

void le_mem_Resume ( void  )

Decompress memory pools after waking from hibernate-to-RAM

This decompresses memory pools after hibernation. After this function returns, Legato tasks may be resumed.

Returns
Nothing

◆ le_mem_SetDestructor()

void le_mem_SetDestructor ( le_mem_PoolRef_t  pool,
le_mem_Destructor_t  destructor 
)

Sets the destructor function for a specified pool.

See Destructors for more information.

Returns
Nothing.
Parameters
[in]poolThe pool.
[in]destructorDestructor function.

◆ le_mem_SetNumObjsToForce()

void le_mem_SetNumObjsToForce ( le_mem_PoolRef_t  pool,
size_t  numObjects 
)

Sets the number of objects that are added when le_mem_ForceAlloc expands the pool.

Returns
Nothing.
Note
The default value is one.
Parameters
[in]poolPool to set the number of objects for.
[in]numObjectsNumber of objects that is added when le_mem_ForceAlloc expands the pool.

◆ le_mem_StrDup()

char* le_mem_StrDup ( le_mem_PoolRef_t  poolRef,
const char *  srcStr 
)

Duplicate a UTF-8 string. The space for the duplicate string will be allocated from the provided memory pool using le_mem_VarAlloc().

Returns
The allocated duplicate of the string. This may later be released with le_mem_Release().
Parameters
poolRefPool from which to allocate the string.
srcStrString to duplicate.

◆ le_mem_TryAlloc()

void* le_mem_TryAlloc ( le_mem_PoolRef_t  pool)

Attempts to allocate an object from a pool.

Returns
Pointer to the allocated object, or NULL if the pool doesn't have any free objects to allocate.
Parameters
[in]poolPool from which the object is to be allocated.

◆ le_mem_TryVarAlloc()

void* le_mem_TryVarAlloc ( le_mem_PoolRef_t  pool,
size_t  size 
)

Attempts to allocate an object from a pool.

Returns
Pointer to the allocated object, or NULL if the pool doesn't have any free objects to allocate.
Parameters
[in]poolPool from which the object is to be allocated.
[in]sizeThe size of block to allocate