|
file | heapmem.h |
| Header file for the dynamic heap memory allocator.
|
|
|
heapmem_zone_t | heapmem_zone_register (const char *name, size_t zone_size) |
| Register a zone with a reserved subdivision of the heap.
|
|
void * | heapmem_zone_alloc (heapmem_zone_t zone, size_t size) |
| Allocate a chunk of memory in the heap.
|
|
void * | heapmem_realloc (void *ptr, size_t size) |
| Reallocate a chunk of memory in the heap.
|
|
void * | heapmem_calloc (size_t nmemb, size_t size) |
| Allocate memory for a zero-initialized array.
|
|
bool | heapmem_free (void *ptr) |
| Deallocate a chunk of memory.
|
|
void | heapmem_stats (heapmem_stats_t *stats) |
| Obtain internal heapmem statistics regarding the allocated chunks.
|
|
void | heapmem_print_debug_info (bool print_chunks) |
| Print debugging information for the heap memory management.
|
|
size_t | heapmem_alignment (void) |
| Obtain the minimum alignment of allocated addresses.
|
|
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 the HEAPMEM_CONF_ARENA_SIZE parameter.
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 147 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_calloc()
void * heapmem_calloc |
( |
size_t | nmemb, |
|
|
size_t | size ) |
Allocate memory for a zero-initialized array.
- Parameters
-
nmemb | The number of elements to allocate. |
size | The size of each element. |
- Returns
- A pointer to the allocated memory, or NULL if the allocation failed.
- See also
- heapmem_alloc
-
heapmem_free
◆ 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 performing any action.
- See also
- heapmem_alloc
-
heapmem_calloc
-
heapmem_realloc
◆ heapmem_print_debug_info()
void heapmem_print_debug_info |
( |
bool | print_chunks | ) |
|
Print debugging information for the heap memory management.
- Parameters
-
print_chunks | Determines whether to print information about all allocated chunks. |
◆ 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_calloc
-
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
-
name | A string containing the name of the zone. |
zone_size | The number of bytes to reserve for the zone. |
- Returns
- A zone ID if the allocation succeeds, or HEAPMEM_ZONE_INVALID if it fails.