The heapmem module is a dynamic heap memory allocator similar to malloc() in standard C.
More...
|
file | heapmem.h |
| Header file for the dynamic heap memory allocator.
|
|
The heapmem module is a dynamic heap memory allocator similar to malloc() in standard C.
The heap memory is managed in a block of static memory, whose size is determined at compile-time by setting HEAPMEM_CONF_ARENA_SIZE parameter. By default, the heap memory is only 1 bytes, which entails that this parameter must be set explicitly in order to be possible to use this module.
Each allocated memory object is referred to as a "chunk". The allocator manages free chunks in a double-linked list. While this adds some memory overhead compared to a single-linked list, it improves the performance of list management.
Internally, allocated chunks can be retrieved using the pointer to the allocated memory returned by heapmem_alloc() and heapmem_realloc(), because the chunk structure immediately precedes the memory of the chunk.
- Note
- If the HEAPMEM_CONF_ARENA_SIZE parameter is not set, the heapmem implementation will not be compiled, which could lead to a linking error if other modules call heapmem functions.
-
This module does not contain a corresponding function to the standard C function calloc().
-
Dynamic memory should be used carefully on memory-constrained, embedded systems, because fragmentation may be induced through various allocation/deallocation patterns, and no guarantees are given regarding the availability of memory.
◆ heapmem_alloc
Allocate a chunk of memory in the general zone of the heap.
- Parameters
-
size | The number of bytes to allocate. |
- Returns
- A pointer to the allocated memory chunk, or NULL if the allocation failed.
- See also
- heapmem_realloc
-
heapmem_free
Definition at line 141 of file heapmem.h.
◆ heapmem_alignment()
size_t heapmem_alignment |
( |
void |
| ) |
|
Obtain the minimum alignment of allocated addresses.
- Returns
- The alignment value, which is a power of two.
◆ heapmem_free()
bool heapmem_free |
( |
void * |
ptr | ) |
|
Deallocate a chunk of memory.
- Parameters
-
- Returns
- A boolean indicating whether the memory could be deallocated.
- Note
- If ptr is NULL, this function will return immediately without without performing any action.
- See also
- heapmem_alloc
-
heapmem_realloc
◆ heapmem_realloc()
void * heapmem_realloc |
( |
void * |
ptr, |
|
|
size_t |
size |
|
) |
| |
Reallocate a chunk of memory in the heap.
- Parameters
-
- Returns
- A pointer to the allocated memory chunk, or NULL if the allocation failed.
- Note
- If ptr is NULL, this function behaves the same as heapmem_alloc.
-
If ptr is not NULL and size is zero, the function deallocates the chunk and returns NULL.
- See also
- heapmem_alloc
-
heapmem_free
◆ heapmem_stats()
void heapmem_stats |
( |
heapmem_stats_t * |
stats | ) |
|
Obtain internal heapmem statistics regarding the allocated chunks.
- Parameters
-
stats | A pointer to an object of type heapmem_stats_t, which will be filled when calling this function. |
This function makes it possible to gain visibility into the internal structure of the heap. One can thus obtain information regarding the amount of memory allocated, overhead used for memory management, and the number of chunks allocated. By using this information, developers can tune their software to use the heapmem allocator more efficiently.
◆ heapmem_zone_alloc()
void * heapmem_zone_alloc |
( |
heapmem_zone_t |
zone, |
|
|
size_t |
size |
|
) |
| |
Allocate a chunk of memory in the heap.
- Parameters
-
zone | The zone in which to allocate the memory. |
size | The number of bytes to allocate. |
- Returns
- A pointer to the allocated memory chunk, or NULL if the allocation failed.
- See also
- heapmem_realloc
-
heapmem_free
◆ heapmem_zone_register()
heapmem_zone_t heapmem_zone_register |
( |
const char * |
name, |
|
|
size_t |
zone_size |
|
) |
| |
Register a zone with a reserved subdivision of the heap.
- Parameters
-
- Returns
- A zone ID if the allocation succeeds, or HEAPMEM_ZONE_INVALID if it fails.