le_mem.h File Reference
Go to the source code of this file.
Data Structures | |
struct | le_mem_PoolStats_t |
Typedefs | |
typedef struct le_mem_Pool * | le_mem_PoolRef_t |
typedef void(* | le_mem_Destructor_t) (void *objPtr) |
Detailed Description
Legato Dynamic Memory Allocation API include file.
Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
Typedef Documentation
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.
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
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.
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] pool Pool from which the object is to be allocated.
|
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] name Name of the pool (will be copied into the Pool). [in] objSize Size of the individual objects to be allocated from this pool (in bytes), e.g., sizeof(MyObject_t).
|
inlinestatic |
Creates a sub-pool. You can't create sub-pools of sub-pools so do not attempt to pass a sub-pool in the superPool parameter.
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.
void le_mem_DeleteSubPool | ( | le_mem_PoolRef_t | subPool | ) |
Deletes a sub-pool.
See Sub-Pools for more information.
- Returns
- Nothing.
- Parameters
-
[in] subPool Sub-pool to be deleted.
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] pool Pool to be expanded. [in] numObjects Number of objects to add to the pool.
|
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] name Name of the pool.
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] pool Pool from which the object is to be allocated.
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] pool The memory pool. [out] namePtr Buffer to store the name of the memory pool. [in] bufSize Size of the buffer namePtr points to.
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] pool Pool where number of objects is to be fetched.
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] pool The pool whose object memory size is to be fetched.
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] pool Pool where object size is to be fetched.
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] pool Pool where stats are to be fetched. [out] statsPtr Pointer to where the stats will be stored.
const 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] pool The memory pool.
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.
void le_mem_ResetStats | ( | le_mem_PoolRef_t | pool | ) |
Resets the statistics for a specified pool.
- Returns
- Nothing.
- Parameters
-
[in] pool Pool where stats are to be reset.
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] pool The pool. [in] destructor Destructor function.
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] pool Pool to set the number of objects for. [in] numObjects Number of objects that is added when le_mem_ForceAlloc expands the pool.
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] pool Pool from which the object is to be allocated.