Heaps

Collaboration diagram for Heaps:

---

Detailed Description

Heap Allocator related APIs.

Operation mode

The heap allocator implements a first-fit strategy and its APIs are functionally equivalent to the usual malloc() and free() library functions. The main difference is that the OS heap APIs are guaranteed to be thread safe.
By enabling the CH_USE_MALLOC_HEAP option the heap manager will use the runtime-provided malloc() and free() as back end for the heap APIs instead of the system provided allocator.

Precondition:

In order to use the heap APIs the CH_USE_HEAP option must be enabled in chconf.h.

Data Structures
union	heap_header
	Memory heap block header. More...
struct	memory_heap
	Structure describing a memory heap. More...
Functions
void	_heap_init (void)
	Initializes the default heap.
void	chHeapInit (MemoryHeap *heapp, void *buf, size_t size)
	Initializes a memory heap from a static memory area.
void *	chHeapAlloc (MemoryHeap *heapp, size_t size)
	Allocates a block of memory from the heap by using the first-fit algorithm.
void	chHeapFree (void *p)
	Frees a previously allocated memory block.
size_t	chHeapStatus (MemoryHeap *heapp, size_t *sizep)
	Reports the heap status.

---

Function Documentation

void _heap_init

(

void

)

Initializes the default heap.

Function Class:

Not an API, this function is for internal use only.

Definition at line 68 of file chheap.c.

References chCoreAlloc(), chMtxInit(), chSemInit(), memory_heap::h_free, memory_heap::h_mtx, memory_heap::h_provider, heap_header::size, and heap_header::u.

Referenced by chSysInit().

Here is the call graph for this function:

void chHeapInit	(	MemoryHeap *	heapp,
		void *	buf,
		size_t	size
	)

Initializes a memory heap from a static memory area.

Precondition:

Both the heap buffer base and the heap size must be aligned to the stkalign_t type size.

In order to use this function the option CH_USE_MALLOC_HEAP must be disabled.

Parameters:

[out]	heapp	pointer to the memory heap descriptor to be initialized
[in]	buf	heap buffer base
[in]	size	heap size

Function Class:

Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 92 of file chheap.c.

References chDbgCheck, chMtxInit(), chSemInit(), memory_heap::h_free, memory_heap::h_mtx, memory_heap::h_provider, MEM_IS_ALIGNED, heap_header::size, and heap_header::u.

Here is the call graph for this function:

void * chHeapAlloc	(	MemoryHeap *	heapp,
		size_t	size
	)

Allocates a block of memory from the heap by using the first-fit algorithm.

The allocated block is guaranteed to be properly aligned for a pointer data type (stkalign_t).

Parameters:

[in]	heapp	pointer to a heap descriptor or NULL in order to access the default heap.
[in]	size	the size of the block to be allocated. Note that the allocated block may be a bit bigger than the requested size for alignment and fragmentation reasons.

Returns:

A pointer to the allocated block.

Return values:

NULL	if the block cannot be allocated.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 125 of file chheap.c.

References memory_heap::h_free, memory_heap::h_provider, MEM_ALIGN_NEXT, heap_header::size, and heap_header::u.

Referenced by chThdCreateFromHeap().

void chHeapFree

(

void *

p

)

Frees a previously allocated memory block.

Parameters:

[in]

p

pointer to the memory block to be freed

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 187 of file chheap.c.

References chDbgAssert, chDbgCheck, memory_heap::h_free, heap_header::size, TRUE, and heap_header::u.

Referenced by chThdRelease().

size_t chHeapStatus	(	MemoryHeap *	heapp,
		size_t *	sizep
	)

Reports the heap status.

Note:

This function is meant to be used in the test suite, it should not be really useful for the application code.

This function is not implemented when the CH_USE_MALLOC_HEAP configuration option is used (it always returns zero).

Parameters:

[in]	heapp	pointer to a heap descriptor or NULL in order to access the default heap.
[in]	sizep	pointer to a variable that will receive the total fragmented free space

Returns:

The number of fragments in the heap.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 243 of file chheap.c.

References memory_heap::h_free, and heap_header::u.