Go to the source code of this file.
Legato Dynamic Memory Allocation API include file.
Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
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.
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. |
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. |
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). |
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. |
Deletes a sub-pool.
See Sub-Pools for more information.
- Returns
- Nothing.
- Parameters
-
[in] | subPool | Sub-pool to be deleted. |
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. |
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. |
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. |
Gets the memory pool's name.
- 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. |
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. |
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. |
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. |
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. |
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
-
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. |
Resets the statistics for a specified pool.
- Returns
- Nothing.
- Parameters
-
[in] | pool | Pool where stats are to be reset. |
Sets the destructor function for a specified pool.
See Destructors for more information.
- Returns
- Nothing.
- Parameters
-
[in] | pool | The pool. |
[in] | destructor | Destructor function. |
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. |
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. |