docs(heap): add readme

dev
Jef Roosens 2023-01-26 11:03:41 +01:00
parent 05b96d1fd6
commit a6bdd39776
Signed by: Jef Roosens
GPG Key ID: B75D4F293C7052DB
1 changed files with 33 additions and 0 deletions

33
src/heap/README.md 100644
View File

@ -0,0 +1,33 @@
This min-heap implementation is a pretty standard binomial heap.
## Representation in memory
A heap consists of one or more binomial trees, each with a different order `k`
and `2^k` total nodes. This heap can contain `2^64 - 1` elements at most, which
is far more than your memory can contain, but it's still fun to mention.
A tree does not have its own memory structure; a node that's the root of a
binomial tree is simply called the tree.
Each node has the following layout:
```c
typedef struct vieter_heap_node {
uint64_t key;
void *data;
struct vieter_heap_node *largest_order;
union {
struct vieter_heap_node *next_tree;
struct vieter_heap_node *next_largest_order;
} ptr;
uint8_t order;
} vieter_heap_node;
```
Each node has a pointer to its child with the largest order (if the node's
order is `0`, this pointer will be NULL). Each non-root node has a pointer to
its sibling with the next-highest order. These pointers allow the children of a
binomial tree to be recombined into a new tree, once their root has been
pop'ed.
Roots point to the binomial tree in the heap with the next largest order.