6160 - plan for safe heap access

Based on apps/handle.subx (commit 4894), but we're able to simplify it
further now that we know more about the situation we find ourselves in.
6 instructions, zero pushes or pops.

Before I can start building this, I need to reorganize my use of handles.
They're going to be fat pointers so we can't store them in registers anymore.

1 files changed, 24 insertions, 0 deletions

diff --git a/mu_summary b/mu_summary
index d098d28f..1ac7a086 100644
--- a/mu_summary
+++ b/mu_summary
@@ -216,3 +216,27 @@ Similarly, conditional loops:
   var/reg: (addr T_f) <- get var/reg: (addr T), f
     where record (product) type T has elements a, b, c, ... of types T_a, T_b, T_c, ...
   var/reg: (addr T_f) <- get var: (addr T), f
+
+## Handles for safe access to the heap
+
+Say we created a handle like this on the stack (it can't be in a register)
+  var x: (handle T)
+  allocate Heap, T, x
+
+You can copy handles to another variable on the stack like this:
+  var y: (handle T)
+  copy-handle-to y, x
+
+You can also save handles inside other user-defined types like this:
+  var y/reg: (addr handle T_f) <- get var: (addr T), f
+  copy-handle-to *y, x
+
+Or this:
+  var y/reg: (addr handle T) <- index arr: (addr array handle T), n
+  copy-handle-to *y, x
+
+Handles can be converted into addresses like this:
+  var y/reg: (addr T) <- lookup x
+
+It's illegal to continue to use this addr after a function that reclaims heap
+memory. You have to repeat the lookup.