Contiki-NG
heapmem: Dynamic heap memory allocator

The heapmem module is a dynamic heap memory allocator similar to malloc() in standard C. More...

Files

file  heapmem.h
 Header file for the dynamic heap memory allocator.
 

Macros

#define heapmem_alloc(size)   heapmem_zone_alloc(HEAPMEM_ZONE_GENERAL, (size))
 Allocate a chunk of memory in the general zone of the heap. More...
 

Functions

heapmem_zone_t heapmem_zone_register (const char *name, size_t zone_size)
 Register a zone with a reserved subdivision of the heap. More...
 
void * heapmem_zone_alloc (heapmem_zone_t zone, size_t size)
 Allocate a chunk of memory in the heap. More...
 
void * heapmem_realloc (void *ptr, size_t size)
 Reallocate a chunk of memory in the heap. More...
 
bool heapmem_free (void *ptr)
 Deallocate a chunk of memory. More...
 
void heapmem_stats (heapmem_stats_t *stats)
 Obtain internal heapmem statistics regarding the allocated chunks. More...
 
size_t heapmem_alignment (void)
 Obtain the minimum alignment of allocated addresses. More...
 

Detailed Description

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.

Macro Definition Documentation

◆ heapmem_alloc

#define heapmem_alloc (   size)    heapmem_zone_alloc(HEAPMEM_ZONE_GENERAL, (size))

Allocate a chunk of memory in the general zone of the heap.

Parameters
sizeThe 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.

Function Documentation

◆ 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
ptrA pointer to a chunk that has been allocated using heapmem_alloc() or heapmem_realloc().
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
ptrA pointer to a chunk that has been allocated using heapmem_alloc() or heapmem_realloc().
sizeThe number of bytes to allocate.
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
statsA 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
zoneThe zone in which to allocate the memory.
sizeThe 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
nameA pointer to a chunk that has been allocated using heapmem_alloc() or heapmem_realloc().
zone_sizeThe number of bytes to reserve for the zone.
Returns
A zone ID if the allocation succeeds, or HEAPMEM_ZONE_INVALID if it fails.