homepage/content/projects/noxos/docs/codebase/mm/heap.h.md

---
title: "heap.h"
summary: "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](https://nerdcult.net/projects/noxos/docs/codebase/mm/heap.h/#heap_segment_t---struct)* | The next segment in the heap                                                             |
| prev  | [heap_segment_T](https://nerdcult.net/projects/noxos/docs/codebase/mm/heap.h/#heap_segment_t---struct)* | 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](https://nerdcult.net/projects/noxos/docs/codebase/mm/heap.h/#heap_segment_t---struct)* | 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](https://nerdcult.net/projects/noxos/docs/codebase/mm/heap.h/#heap_memory_allocateheap-size---function-void) 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.