LwMEM¶
-
group
LWMEM
Lightweight dynamic memory manager.
Defines
-
LWMEM_ARRAYSIZE
(x)¶ Get size of statically allocated array.
- Return
Number of elements in array
- Parameters
[in] x
: Object to get array size of
-
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
[in] regions
: Array of regions with address and its size. Regions must be in increasing order (start address) and must not overlap in-between[in] len
: 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
[in] size
: 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
[in] nitems
: Number of elements to be allocated[in] size
: 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
[in] ptr
: Memory block previously allocated with one of allocation functions. It may be set toNULL
to create new clean allocation[in] size
: 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
[in] ptrptr
: Pointer to pointer to allocated memory. Must not be set toNULL
. If reallocation is successful, it modified where pointer points to, or sets it toNULL
in case offree
operation[in] size
: 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
[in] ptr
: 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
[in] ptrptr
: Pointer to pointer to allocated memory. When set to nonNULL
, 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
- Return
Block size for user in units of bytes
- Parameters
[in] ptr
: Pointer to allocated memory
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.
- Return
0
on failure, number of final regions used for memory manager on success- Note
This function is not thread safe when used with operating system. It must be called only once to setup memory regions
- Parameters
[in] lw
: LwMEM instance. Set toNULL
to use default instance[in] regions
: Array of regions with address and its size. Regions must be in increasing order (start address) and must not overlap in-between[in] len
: Number of regions in array
-
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
- Return
Pointer to allocated memory on success,
NULL
otherwise- Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
[in] lw
: LwMEM instance. Set toNULL
to use default instance[in] region
: Optional region instance within LwMEM instance to force allocation from. Set toNULL
to use any region within LwMEM instance[in] size
: Number of bytes to allocate
-
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
- Return
Pointer to allocated memory on success,
NULL
otherwise- Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
[in] lw
: LwMEM instance. Set toNULL
to use default instance[in] region
: Optional region instance within LwMEM instance to force allocation from. Set toNULL
to use any region within LwMEM instance[in] nitems
: Number of elements to be allocated[in] size
: Size of each element, in units of bytes
-
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
:- Note
This function may only be used with allocations returned by any of
_from
API functions
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
- Return
Pointer to allocated memory on success,
NULL
otherwise- Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
[in] lw
: LwMEM instance. Set toNULL
to use default instance[in] region
: Pointer to region to allocate from. Set toNULL
to use any region within LwMEM instance. Instance must be the same as used during allocation procedure[in] ptr
: Memory block previously allocated with one of allocation functions. It may be set toNULL
to create new clean allocation[in] size
: Size of new memory to reallocate
-
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
- Return
1
if successfully reallocated,0
otherwise- Note
This function is thread safe when LWMEM_CFG_OS is enabled
- Parameters
[in] lw
: LwMEM instance. Set toNULL
to use default instance[in] region
: Pointer to region to allocate from. Set toNULL
to use any region within LwMEM instance. Instance must be the same as used during allocation procedure[in] ptr
: Pointer to pointer to allocated memory. Must not be set toNULL
. If reallocation is successful, it modified where pointer points to, or sets it toNULL
in case offree
operation[in] size
: New requested size
-
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
[in] lw
: LwMEM instance. Set toNULL
to use default instance. Instance must be the same as used during allocation procedure
- Parameters
[in] ptr
: 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
[in] lw
: LwMEM instance. Set toNULL
to use default instance. Instance must be the same as used during allocation procedure[in] ptr
: Pointer to pointer to allocated memory. When set to nonNULL
, pointer is freed and set toNULL
-
size_t
lwmem_get_size_ex
(lwmem_t *const lw, void *ptr)¶ Get user size of allocated memory.
- Return
Block size for user in units of bytes
- Parameters
[in] lw
: LwMEM instance. Set toNULL
to use default instance. Instance must be the same as used during allocation procedure[in] ptr
: Pointer to allocated memory
-
struct
lwmem_block_t
¶ - #include <lwmem.h>
Memory block 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_block_t
-
struct
lwmem_region_t
¶ - #include <lwmem.h>
Memory region descriptor.
-