Go to the source code of this file.
|
LE_DECLARE_INLINE 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) |
|
Legato Dynamic Memory Allocation API include file.
Copyright (C) Sierra Wireless Inc.
◆ LE_COMPONENT_NAME
#define LE_COMPONENT_NAME |
◆ LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES
#define LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES 32 |
◆ le_mem_Destructor_t
typedef void(* le_mem_Destructor_t) (void *objPtr) |
Prototype for destructor functions.
- Parameters
-
objPtr | Pointer 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
◆ le_mem_CreatePool()
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] | name | Name of the pool inside the component. |
[in] | objSize | Size of the individual objects to be allocated from this pool (in bytes), e.g., sizeof(MyObject_t). |
◆ le_mem_ExpandPool()
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] | pool | Pool to be expanded. |
[in] | numObjects | Number of objects to add to the pool. |
◆ le_mem_TryAlloc()
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] | pool | Pool from which the object is to be allocated. |
◆ le_mem_AssertAlloc()
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] | pool | Pool from which the object is to be allocated. |
◆ le_mem_ForceAlloc()
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] | pool | Pool from which the object is to be allocated. |
◆ le_mem_TryVarAlloc()
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] | pool | Pool from which the object is to be allocated. |
[in] | size | The size of block to allocate |
◆ le_mem_AssertVarAlloc()
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] | pool | Pool from which the object is to be allocated. |
[in] | size | The size of block to allocate |
◆ le_mem_ForceVarAlloc()
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] | pool | Pool from which the object is to be allocated. |
[in] | size | The size of block to allocate |
◆ le_mem_SetNumObjsToForce()
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] | pool | Pool to set the number of objects for. |
[in] | numObjects | Number of objects that is added when le_mem_ForceAlloc expands the 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] | objPtr | Pointer to the object to be released. |
◆ 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] | objPtr | Pointer to the object. |
◆ 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] | objPtr | Pointer to the object to get size of. |
◆ 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] | objPtr | Pointer to the object. |
◆ le_mem_SetDestructor()
Sets the destructor function for a specified pool.
See Destructors for more information.
- Returns
- Nothing.
- Parameters
-
[in] | pool | The pool. |
[in] | destructor | Destructor function. |
◆ le_mem_GetStats()
Fetches the statistics for a specified pool.
- Returns
- Nothing. Uses output parameter instead.
- Parameters
-
[in] | pool | Pool where stats are to be fetched. |
[out] | statsPtr | Pointer to where the stats will be stored. |
◆ le_mem_ResetStats()
Resets the statistics for a specified pool.
- Returns
- Nothing.
- Parameters
-
[in] | pool | Pool where stats are to be reset. |
◆ le_mem_GetName()
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] | pool | The memory pool. |
[out] | namePtr | Buffer to store the name of the memory pool. |
[in] | bufSize | Size of the buffer namePtr points to. |
◆ le_mem_IsSubPool()
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
-
◆ le_mem_GetObjectCount()
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] | pool | Pool where number of objects is to be fetched. |
◆ le_mem_GetObjectSize()
Fetches the size of the objects in a specified pool (in bytes).
- Returns
- Object size, in bytes.
- Parameters
-
[in] | pool | Pool where object size is to be fetched. |
◆ le_mem_GetObjectFullSize()
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] | pool | The pool whose object memory size is to be fetched. |
◆ le_mem_FindPool()
Finds a pool based on the pool's name.
- Returns
- Reference to the pool, or NULL if the pool doesn't exist.
- Parameters
-
[in] | name | Name of the pool inside the component. |
◆ le_mem_CreateSubPool()
Creates a sub-pool.
See Sub-Pools for more information.
- Returns
- Reference to the sub-pool.
- Parameters
-
[in] | superPool | Super-pool. |
[in] | name | Name of the sub-pool (will be copied into the sub-pool). |
[in] | numObjects | Number of objects to take from the super-pool. |
◆ le_mem_CreateReducedPool()
Creates a sub-pool of smaller objects.
See Reduced-size pools for more information.
- Returns
- Reference to the sub-pool.
- Parameters
-
[in] | superPool | Super-pool. |
[in] | name | Name of the sub-pool (will be copied into the sub-pool). |
[in] | numObjects | Minimum number of objects in the subpool by default. |
[in] | objSize | Minimum size of objects in the subpool. |
◆ le_mem_DeleteSubPool()
Deletes a sub-pool.
See Sub-Pools for more information.
- Returns
- Nothing.
- Parameters
-
[in] | subPool | Sub-pool to be deleted. |
◆ 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] | freeStartPtr | Beginning of unused memory which does not need to be preserved in hibernation |
[out] | freeEndPtr | End of unused memory |
◆ 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_StrDup()
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
-
poolRef | Pool from which to allocate the string. |
srcStr | String to duplicate. |