heapmem: Dynamic heap memory allocator

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

Macros
#define	HEAPMEM_ZONE_DEFINE(varname, bufsize)
	Define a zone with its own static memory buffer.

Functions
void *	heapmem_zone_alloc (heapmem_zone_t *zone, size_t size)
	Allocate a chunk of memory in the specified zone.
bool	heapmem_zone_free (heapmem_zone_t *zone, void *ptr)
	Deallocate a chunk of memory in the specified zone.
void *	heapmem_zone_realloc (heapmem_zone_t *zone, void *ptr, size_t size)
	Reallocate a chunk of memory in the specified zone.
void *	heapmem_zone_calloc (heapmem_zone_t *zone, size_t nmemb, size_t size)
	Allocate memory for a zero-initialized array in the specified zone.
void	heapmem_zone_stats (heapmem_zone_t *zone, heapmem_stats_t *stats)
	Obtain internal statistics for a heapmem zone.
void	heapmem_zone_print_debug_info (heapmem_zone_t *zone, bool print_chunks)
	Print debugging information for a heapmem zone.

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

HeapMem zones provide independent heaps with their own static memory buffers. Each zone has its own free list and usage tracking, so fragmentation in one zone cannot affect another. Use HEAPMEM_ZONE_DEFINE() to create a zone with a dedicated buffer.

Note

The HEAPMEM_CONF_ARENA_SIZE parameter enables the general zone and the convenience macros (heapmem_alloc, heapmem_free, etc.). Zone-specific functions (heapmem_zone_alloc, etc.) and the HEAPMEM_ZONE_DEFINE macro are always available.

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_ZONE_DEFINE

#define HEAPMEM_ZONE_DEFINE	(		varname,
			bufsize )

Value:

  static char varname##_buf_[bufsize] CC_ALIGN(HEAPMEM_ALIGNMENT);         \
  static heapmem_zone_t varname = {                                        \
    .name = #varname,                                                      \
    .heap_base = varname##_buf_,                                           \
    .arena_size = bufsize,                                                 \
  }

Define a zone with its own static memory buffer.

Parameters

varname	The variable name for the zone.
bufsize	The size of the zone's memory buffer in bytes.

This macro creates a file-scoped zone with a statically allocated buffer. The zone provides an independent heap that is isolated from all other zones.

Example usage: HEAPMEM_ZONE_DEFINE(packet_zone, 4096); void *p = heapmem_zone_alloc(&packet_zone, 128); heapmem_zone_free(&packet_zone, p);

Definition at line 151 of file heapmem.h.

Function Documentation

heapmem_zone_alloc()

void * heapmem_zone_alloc	(	heapmem_zone_t *	zone,
		size_t	size )

Allocate a chunk of memory in the specified zone.

Parameters

zone	A pointer to the zone in which to allocate the memory, or NULL to use the general zone.
size	The number of bytes to allocate.

Returns

A pointer to the allocated memory chunk, or NULL if the allocation failed.

See also

heapmem_zone_realloc

heapmem_zone_free

Definition at line 362 of file heapmem.c.

heapmem_zone_calloc()

void * heapmem_zone_calloc	(	heapmem_zone_t *	zone,
		size_t	nmemb,
		size_t	size )

Allocate memory for a zero-initialized array in the specified zone.

Parameters

zone	A pointer to the zone in which to allocate the memory, or NULL to use the general zone.
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_zone_alloc

heapmem_zone_free

Definition at line 586 of file heapmem.c.

heapmem_zone_free()

bool heapmem_zone_free	(	heapmem_zone_t *	zone,
		void *	ptr )

Deallocate a chunk of memory in the specified zone.

Parameters

zone	A pointer to the zone from which the memory was allocated, or NULL to use the general zone.
ptr	A pointer to a chunk that has been allocated using heapmem_zone_alloc() or heapmem_zone_realloc().

Returns

A boolean indicating whether the memory could be deallocated.

See also

heapmem_zone_alloc

heapmem_zone_realloc

Definition at line 415 of file heapmem.c.

heapmem_zone_print_debug_info()

void heapmem_zone_print_debug_info	(	heapmem_zone_t *	zone,
		bool	print_chunks )

Print debugging information for a heapmem zone.

Parameters

zone	A pointer to the zone to query.
print_chunks	Determines whether to print information about all allocated chunks.

Definition at line 622 of file heapmem.c.

References heapmem_zone_stats().

heapmem_zone_realloc()

void * heapmem_zone_realloc	(	heapmem_zone_t *	zone,
		void *	ptr,
		size_t	size )

Reallocate a chunk of memory in the specified zone.

Parameters

zone	A pointer to the zone in which to reallocate the memory, or NULL to use the general zone.
ptr	A pointer to a chunk that has been allocated using heapmem_zone_alloc() or heapmem_zone_realloc().
size	The 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_zone_alloc.

If ptr is not NULL and size is zero, the function deallocates the chunk and returns NULL.

See also

heapmem_zone_alloc

heapmem_zone_free

Definition at line 553 of file heapmem.c.

heapmem_zone_stats()

void heapmem_zone_stats	(	heapmem_zone_t *	zone,
		heapmem_stats_t *	stats )

Obtain internal statistics for a heapmem zone.

Parameters

zone	A pointer to the zone to query.
stats	A pointer to an object of type heapmem_stats_t, which will be filled when calling this function.

Definition at line 594 of file heapmem.c.

Referenced by heapmem_zone_print_debug_info().