# heap.h

Dynamic memory allocator.

# `heap_segment_T` - struct
This header lies in memory, directly before the accessible buffer of the related segment.

| Name  | Type            | Description                                                                              |
|-------|-----------------|------------------------------------------------------------------------------------------|
| magic | uint32_t        | An out of bounds memory write would override this, what would indicate a heap corruption |
| size  | uint64_t        | The size of the segment                                                                  |
| free  | bool            | If this is set, the segment is reclaimable                                               |
| next  | heap_segment_T* | The next segment in the heap                                                             |
| prev  | heap_segment_T* | The previous segment in the heap                                                         |


# `heap_T` - struct

| Name         | Type            | Description                                                 |
|--------------|-----------------|-------------------------------------------------------------|
| start        | void*           | The start of the heaps segment pool                         |
| end          | void*           | The current end of the heaps segment pool (growing upwards) |
| last_segment | heap_segment_T* | The current last segment in the heaps segment pool          |

# `heap_init(heap*, base)` - function (void)
Initializes **_heap_** at **_base_** (virtual address).
It will automatically map some page frames to that address.

# `heap_memory_allocate(heap*, size)` - function (void)
Returns a pointer to a free usable memory location, that has at least the given **_size_**.
It will return `NULL` and log an error, if the heap is corrupted.
Because this function iterates over the entire heap to find a free segment, it is kinda slow.

# `heap_memory_free(heap*, address)` - function (void)
Frees a with heap_memory_allocate() created heap segment, and makes it usable again.
Does nothing, if the address doesn't point to a valid heap segment.

# `heap_dump_segments(heap*)` - function (void)
Logs a complete list, of all heap segments.
Useful, when debugging / testing the heap.

# `heap_destruct(heap*)` - function (void)
Invalidates all segments of a heap, frees all used page frames and unmaps them.