docs(heap): add readme

src/heap/README.md

@@ -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.