heap.h File Reference

This is a standard MushLib heap header. See standard implementation in lib/base/heap.c. More...

#include "generic.h"

Include dependency graph for heap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	allocation_exception_id   0x1
#define	allocation_exception_type   "Allocation Exception"
#define	heap_exception_id   0x2
#define	heap_exception_type   "Heap Exception"
#define	size_of(structure)   (size(structure) / sizeof(typeof(*structure)))

Functions
precise	occupation ()
void	initialize_heap (void *start_address, u_dword initial_size)
void *	ralloc (u_dword size)
void *	zalloc (u_dword size)
void *	challoc (void *structure, u_dword new_size)
void	unalloc (void *structure)
boolean	is_in_heap (void *structure)
u_dword	size (void *structure)

Detailed Description

This is a standard MushLib heap header. See standard implementation in lib/base/heap.c.

This heap solves a strange C stdlib issue - each pointer in heap has a header that contains allocated data size. One can determine allocated space (in pieces, e.g. array length) using size_of macro.

It's also possible to determine whether a structure belongs to heap or not (using is_in_heap function).

Definition in file heap.h.

Macro Definition Documentation

allocation_exception_id

#define allocation_exception_id   0x1

Allocation exception ID. Indicates that a program asked for more space than heap can provide. Will be thrown by default allocation exception handler. Should be thrown if a custom program is terminated because of allocation exception.

Definition at line 25 of file heap.h.

allocation_exception_type

#define allocation_exception_type   "Allocation Exception"

Allocation exception type. May be used by custom allocation exception handlers.

Definition at line 30 of file heap.h.

heap_exception_id

#define heap_exception_id   0x2

Heap exception ID. Indicates that there was an attempt to calculate size or free a structure that is located outside of the heap. Will be thrown by default heap exception handler. Should be thrown if a custom program is terminated because of heap exception.

Definition at line 38 of file heap.h.

heap_exception_type

#define heap_exception_type   "Heap Exception"

Heap exception type. May be used by custom heap exception handlers.

Definition at line 43 of file heap.h.

size_of

#define size_of

(

structure

)

(size(structure) / sizeof(typeof(*structure)))

Macro for for structure located in heap size calculation (in units). For example, can be used to calculate array of structures length. Throws heap exception if the given pointer is outside of the current heap.

Parameters

structure

a pointer to the structure.

Returns

structure size (in units).

Definition at line 53 of file heap.h.

Function Documentation

occupation()

precise occupation

(

)

Function for heap occupation calculation.

Returns

percent of allocated space in this heap.

Definition at line 69 of file lib/base/heap.c.

References get_header(), and header.

initialize_heap()

void initialize_heap	(	void *	start_address,
		u_dword	initial_size
	)

Function for heap initialization, sets up singleton heap header. This implementation of heap has fixed size, and so doesn't rely on paging. That's enough for kernel and basic app needs, TODO: provide another heap implementation for extended MushLib.

Parameters

start_address	pointer to the start of the heap.
initial_size	initial size of the heap.

Definition at line 116 of file lib/base/heap.c.

References allocation_exception_id, handle_allocation_exception(), and header.

Referenced by _start().

ralloc()

void * ralloc

(

u_dword

size

)

Function for allocation of a raw heap block. Searches for a place of suitable size to fit a structure of requested size in. Throws allocation exception if no free space is available.

Parameters

size	requested block size.

Returns

pointer to the neewly allocated block.

Definition at line 125 of file lib/base/heap.c.

References allocate_space(), allocation_exception_id, allocation_exception_type, get_header(), header, and size().

Referenced by challoc(), and zalloc().

zalloc()

void * zalloc

(

u_dword

size

)

Function for allocation of a heap block and clearing it. Does the same as ralloc, but sets every allocated byte to zero. Throws allocation exception if no free space is available.

Parameters

size	requested block size.

Returns

pointer to the neewly allocated block.

Definition at line 171 of file lib/base/heap.c.

References ralloc(), and size().

challoc()

void * challoc	(	void *	structure,
		u_dword	new_size
	)

Function for heap block size alteration. Attempts to alter size in-place and copys the block only if in-place growth is not available. Throws heap exception if the structure is located outside of the heap.

Parameters

structure	pointer to the structure for allocation size changing.
new_size	new requested size of the structure.

Returns

pointer to the new structure.

Definition at line 177 of file lib/base/heap.c.

References get_header(), ralloc(), size(), and unalloc().

unalloc()

void unalloc

(

void *

structure

)

Function for heap block unallocation. Throws heap exception if the structure is located outside of the heap.

Parameters

structure

pointer to the structure for unallocation.

Definition at line 193 of file lib/base/heap.c.

References get_header(), and header.

Referenced by challoc().

is_in_heap()

boolean is_in_heap

(

void *

structure

)

Function for determining whether the structure is inside the heap or outside.

Parameters

structure

a pointer to the structure.

Returns

true is structure is in heap, false otherwise.

Definition at line 49 of file lib/base/heap.c.

References header.

Referenced by get_header().

size()

u_dword size

(

void *

structure

)

Function for structure located in heap size calculation (in bytes). Throws heap exception if the given pointer is outside of the current heap.

Parameters

structure

a pointer to the structure.

Returns

structure size (in bytes).

Definition at line 65 of file lib/base/heap.c.

References get_header().

Referenced by allocate_space(), challoc(), ralloc(), and zalloc().