docs/: forwarding pointers, lgc, todos, ...

docs/_config.yml

@@ -46,6 +46,12 @@ callouts:
   note:
     title: Note
     color: blue
+  remark:
+    title: Remark
+    color: green
+  todo:
+    title: TODO
+    color: red
 aux_links:
   MaPLe on GitHub:
     - https://github.com/MPLLang/mpl

docs/compiler/index.md

@@ -3,4 +3,5 @@ layout: page
 title: Compiler
 ---
 
-TODO...
+{: .todo}
+...

docs/rts/em/index.md

@@ -6,4 +6,5 @@ parent: Runtime System
 
 # Entanglement Detection and Management
 
-TODO...
+{: .todo}
+...

docs/rts/mm/cgc.md

@@ -6,4 +6,5 @@ parent: Memory Management
 
 # Concurrent Garbage Collection (CGC)
 
-TODO...
+{: .todo}
+...

docs/rts/mm/fwd-ptr.md

@@ -6,4 +6,28 @@ parent: Memory Management
 
 # Forwarding Pointers
 
-TODO...
+A **forwarding pointer** redirects from an old version of an object to a new
+version. Forwarding pointers are created temporarily by
+[Local Garbage Collection (LGC)](lgc.html) when copying live objects into fresh
+heaps.
+
+{: .note}
+Assuming nothing has gone terribly wrong, forwarding pointers should
+be "invisible" to the source program. In particular, during an LGC, the thread
+that owns the heaps in-scope of the collection is paused. Any other thread
+which attempts to access an object in-scope of the collection is protected
+against witnessing a forwarding pointer by the
+[Read Barrier](read-barrier.html).
+
+
+To **forward** an object, we:
+  1. copy the object to a new location, and
+  2. overwrite the (old) object's [Header](header.html) with a pointer to the new location.
+
+Note that forwarding pointers are stored in place of the [Header](header.html).
+We can distinguish between a header and a forwarding
+pointer by checking the least-significant bit. Every header will have a 1 in
+the least-significant position; forwarding pointers will always have a 0
+in this position, due to alignment constraints.
+
+![Forwarding an object]({{site.baseurl}}/assets/forward.png){:width="80%"}

docs/rts/mm/heap.md

@@ -24,4 +24,5 @@ in `runtime/gc/hierarchical-heap.h`. A companion type,
 and also keep track of old `HM_HierarchicalHeap` structs that can be
 reclaimed.
 
-TODO...
+{: .todo}
+...

docs/rts/mm/index.md

@@ -6,6 +6,7 @@ parent: Runtime System
 
 # Memory Management
 
-TODO...
+{: .todo}
+...
 
 Main source location: [`runtime/gc/`](https://github.com/MPLLang/mpl/tree/main/runtime/gc)

docs/rts/mm/lgc.md

@@ -0,0 +1,18 @@
+---
+layout: page
+title: Local Garbage Collection
+parent: Memory Management
+---
+
+# Local Garbage Collection (LGC)
+
+In the [Heap Hierarchy](heap.html), leaf heaps (and nearby ancestors, generally
+deep in the hierarchy) are subjected to a hybrid copying/in-place collection
+algorithm called **Local Garbage Collection**, or **LGC** for short.
+The algorithm is hybrid in the sense that certain "pinned" objects are kept
+in-place but all other live objects are forwarded (copied) into fresh heaps.
+The forwarding component of the algorithm is an adaptation of
+[Cheney's classic algorithm](https://en.wikipedia.org/wiki/Cheney%27s_algorithm).
+
+{: .todo}
+...

docs/rts/mm/obj-type-table.md

@@ -6,4 +6,5 @@ parent: Memory Management
 
 # The Object Type Table
 
-TODO...
+{: .todo}
+...

docs/rts/mm/read-barrier.md

@@ -0,0 +1,8 @@
+---
+layout: page
+title: Read Barrier
+parent: Memory Management
+---
+
+{: .todo}
+...

docs/rts/mm/stack.md

@@ -6,4 +6,5 @@ parent: Memory Management
 
 # Call-Stacks
 
-TODO...
+{: .todo}
+...

docs/rts/sched/index.md

@@ -8,6 +8,7 @@ parent: Runtime System
 
 MPL features a work-stealing scheduler which assigns tasks to processors.
 
-TODO...
+{: .todo}
+...
 
 Main source location: [`basis-library/schedulers/par-pcall/`](https://github.com/MPLLang/mpl/tree/main/basis-library/schedulers/par-pcall/)