LwMEM¶
-
group
LWMEM
Lightweight dynamic memory manager.
Defines
-
LWMEM_ARRAYSIZE
(x)¶ Get size of statically allocated array.
- Parameters
x – [in] Object to get array size of
- Returns
Number of elements in array
-
lwmem_assignmem
(regions, len)¶ Note
This is a wrapper for lwmem_assignmem_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
regions – [in] Array of regions with address and its size. Regions must be in increasing order (start address) and must not overlap in-between
len – [in] Number of regions in array
-
lwmem_malloc
(size)¶ Note
This is a wrapper for lwmem_malloc_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
size – [in] Size to allocate in units of bytes
-
lwmem_calloc
(nitems, size)¶ Note
This is a wrapper for lwmem_calloc_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
nitems – [in] Number of elements to be allocated
size – [in] Size of each element, in units of bytes
-
lwmem_realloc
(ptr, size)¶ Note
This is a wrapper for lwmem_realloc_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
ptr – [in] Memory block previously allocated with one of allocation functions. It may be set to
NULL
to create new clean allocationsize – [in] Size of new memory to reallocate
-
lwmem_realloc_s
(ptrptr, size)¶ Note
This is a wrapper for lwmem_realloc_s_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
ptrptr – [in] Pointer to pointer to allocated memory. Must not be set to
NULL
. If reallocation is successful, it modified where pointer points to, or sets it toNULL
in case offree
operationsize – [in] New requested size
-
lwmem_free
(ptr)¶ Note
This is a wrapper for lwmem_free_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
ptr – [in] Memory to free.
NULL
pointer is valid input
-
lwmem_free_s
(ptrptr)¶ Note
This is a wrapper for lwmem_free_s_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
ptrptr – [in] Pointer to pointer to allocated memory. When set to non
NULL
, pointer is freed and set toNULL
-
lwmem_get_size
(ptr)¶ Note
This is a wrapper for lwmem_get_size_ex function. It operates in default LwMEM instance and uses first available region for memory operations
- Parameters
ptr – [in] Pointer to allocated memory
- Returns
Block size for user in units of bytes
Functions
-
size_t
lwmem_assignmem_ex
(lwmem_t *const lw, const lwmem_region_t *regions, const size_t len)¶ Initializes and assigns user regions for memory used by allocator algorithm.
Note
This function is not thread safe when used with operating system. It must be called only once to setup memory regions
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instanceregions – [in] Array of regions with address and its size. Regions must be in increasing order (start address) and must not overlap in-between
len – [in] Number of regions in array
- Returns
0
on failure, number of final regions used for memory manager on success
-
void *
lwmem_malloc_ex
(lwmem_t *const lw, const lwmem_region_t *region, const size_t size)¶ Allocate memory of requested size in specific lwmem instance and optional region.
Note
This is an extended malloc version function declaration to support advanced features
Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instanceregion – [in] Optional region instance within LwMEM instance to force allocation from. Set to
NULL
to use any region within LwMEM instancesize – [in] Number of bytes to allocate
- Returns
Pointer to allocated memory on success,
NULL
otherwise
-
void *
lwmem_calloc_ex
(lwmem_t *const lw, const lwmem_region_t *region, const size_t nitems, const size_t size)¶ Allocate contiguous block of memory for requested number of items and its size in specific lwmem instance and region.
It resets allocated block of memory to zero if allocation is successful
Note
This is an extended calloc version function declaration to support advanced features
Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instanceregion – [in] Optional region instance within LwMEM instance to force allocation from. Set to
NULL
to use any region within LwMEM instancenitems – [in] Number of elements to be allocated
size – [in] Size of each element, in units of bytes
- Returns
Pointer to allocated memory on success,
NULL
otherwise
-
void *
lwmem_realloc_ex
(lwmem_t *const lw, const lwmem_region_t *region, void *const ptr, const size_t size)¶ Reallocates already allocated memory with new size in specific lwmem instance and region.
Function behaves differently, depends on input parameter of
ptr
andsize
:ptr == NULL; size == 0
: Function returnsNULL
, no memory is allocated or freedptr == NULL; size > 0
: Function tries to allocate new block of memory withsize
length, equivalent tomalloc(region, size)
ptr != NULL; size == 0
: Function frees memory, equivalent tofree(ptr)
ptr != NULL; size > 0
: Function tries to allocate new memory of copy content before returning pointer on success
Note
This function may only be used with allocations returned by any of
_from
API functionsNote
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instanceregion – [in] Pointer to region to allocate from. Set to
NULL
to use any region within LwMEM instance. Instance must be the same as used during allocation procedureptr – [in] Memory block previously allocated with one of allocation functions. It may be set to
NULL
to create new clean allocationsize – [in] Size of new memory to reallocate
- Returns
Pointer to allocated memory on success,
NULL
otherwise
-
uint8_t
lwmem_realloc_s_ex
(lwmem_t *const lw, const lwmem_region_t *region, void **const ptr, const size_t size)¶ Safe version of realloc_ex function.
After memory is reallocated, input pointer automatically points to new memory to prevent use of dangling pointers. When reallocation is not successful, original pointer is not modified and application still has control of it.
It is advised to use this function when reallocating memory.
Function behaves differently, depends on input parameter of
ptr
andsize
:ptr == NULL
: Invalid input, function returns0
*ptr == NULL; size == 0
: Function returns0
, no memory is allocated or freed*ptr == NULL; size > 0
: Function tries to allocate new block of memory withsize
length, equivalent tomalloc(size)
*ptr != NULL; size == 0
: Function frees memory, equivalent tofree(ptr)
, sets input pointer pointing toNULL
*ptr != NULL; size > 0
: Function tries to reallocate existing pointer with new size and copy content to new block
Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instanceregion – [in] Pointer to region to allocate from. Set to
NULL
to use any region within LwMEM instance. Instance must be the same as used during allocation procedureptr – [in] Pointer to pointer to allocated memory. Must not be set to
NULL
. If reallocation is successful, it modified where pointer points to, or sets it toNULL
in case offree
operationsize – [in] New requested size
- Returns
1
if successfully reallocated,0
otherwise
-
void
lwmem_free_ex
(lwmem_t *const lw, void *const ptr)¶ Free previously allocated memory using one of allocation functions in specific lwmem instance.
Note
This is an extended free version function declaration to support advanced features
Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instance. Instance must be the same as used during allocation procedureptr – [in] Memory to free.
NULL
pointer is valid input
-
void
lwmem_free_s_ex
(lwmem_t *const lw, void **const ptr)¶ Safe version of free function.
After memory is freed, input pointer is safely set to
NULL
to prevent use of dangling pointers.It is advised to use this function when freeing memory.
Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instance. Instance must be the same as used during allocation procedureptr – [in] Pointer to pointer to allocated memory. When set to non
NULL
, pointer is freed and set toNULL
-
size_t
lwmem_get_size_ex
(lwmem_t *const lw, void *ptr)¶ Get user size of allocated memory.
- Parameters
lw – [in] LwMEM instance. Set to
NULL
to use default instance. Instance must be the same as used during allocation procedureptr – [in] Pointer to allocated memory
- Returns
Block size for user in units of bytes
-
struct
lwmem_block_t
¶ - #include <lwmem.h>
Memory block structure.
-
struct
lwmem_stats_t
¶ - #include <lwmem.h>
Statistics structure.
-
struct
lwmem_t
¶ - #include <lwmem.h>
LwMEM main structure.
Public Members
-
lwmem_block_t
start_block
¶ Holds beginning of memory allocation regions
-
lwmem_block_t *
end_block
¶ Pointer to the last memory location in regions linked list
-
size_t
mem_available_bytes
¶ Memory size available for allocation
-
size_t
mem_regions_count
¶ Number of regions used for allocation
-
LWMEM_CFG_OS_MUTEX_HANDLE
mutex
¶ System mutex for OS
-
lwmem_stats_t
stats
¶ Statistics
-
lwmem_block_t
-
struct
lwmem_region_t
¶ - #include <lwmem.h>
Memory region descriptor.
-