unfinished

Author: riaqn

jane/doc/extensions/stack/intro.md

@@ -1,65 +1,59 @@
-# Introduction to Local Allocations
+# Introduction to Stack Allocations
 
 See also the full feature [reference](reference.md) and [common pitfalls](pitfalls.md).
 
-Instead of allocating values normally on the GC heap, local
-allocations allow you to stack-allocate values using the new `local_`
-keyword:
+Instead of allocating values normally on the GC heap, you stack-allocate values
+using the new `stack_` keyword:
 
 ```ocaml
-let local_ x = { foo; bar } in
-...
-```
-
-or equivalently, by putting the keyword on the expression itself:
-
-```ocaml
-let x = local_ { foo; bar } in
+let x = stack_ { foo; bar } in
 ...
 ```
 
 These values live on a separate stack, and are popped off at the end
 of the _region_. Generally, the region ends when the surrounding
 function returns, although read [the reference](reference.md) for more
-details.
+details. Annotating `stack_` on non-allocations is meaningless and trigger type
+errors.
 
 This helps performance in a couple of ways: first, the same few hot
 cache lines are constantly reused, so the cache footprint is lower than
-usual. More importantly, local allocations will never trigger a GC,
+usual. More importantly, stack allocations will never trigger a GC,
 and so they're safe to use in low-latency code that must currently be
 zero-alloc.
 
-However, for this to be safe, local allocations must genuinely be
-local. Since the memory they occupy is reused quickly, we must ensure
-that no dangling references to them escape. This is checked by the
-type-checker, and you'll see new error messages if local values leak:
+However, for this to be safe, stack-allocated values must not be used after the
+current region are destroyed. This is ensured by the type-checker as
+follows: stack-allocated values will
+be `local` to the current region. Heap-allocated values will be `global`. `local`
+values cannot escape the current region, but `global` values can. If a `local`
+value tries to escape the current region, you'll see error messages:
 
 ```ocaml
-# let local_ thing = { foo; bar } in
+# let thing = stack_ { foo; bar } in
   some_global := thing;;
                  ^^^^^
 Error: This value escapes its region
 ```
 
-Most of the types of allocation that OCaml does can be locally
-allocated: tuples, records, variants, closures, boxed numbers,
-etc. Local allocations are also possible from C stubs, although this
-requires code changes to use the new `caml_alloc_local` instead of
-`caml_alloc`. A few types of allocation cannot be locally allocated,
-though, including first-class modules, classes and objects, and
-exceptions. The contents of mutable fields (inside `ref`s, `array`s
-and mutable record fields) also cannot be locally allocated.
+Most of the types of allocation that OCaml does can be stack-allocated: tuples,
+records, variants, closures, boxed numbers, etc. Stack allocations are also
+possible from C stubs, although this requires code changes to use the new
+`caml_alloc_local` instead of `caml_alloc`. A few types of allocation cannot be
+stack-allocated, though, including first-class modules, classes and objects,
+and exceptions. The contents of mutable fields (inside `ref`s, `array`s and
+mutable record fields) also cannot be stack-allocated.
 
 
 ## Local parameters
 
 Generally, OCaml functions can do whatever they like with their
 arguments: use them, return them, capture them in closures or store
 them in globals, etc. This is a problem when trying to pass around
-locally-allocated values, since we need to guarantee they do not
+`local` values, since we need to guarantee they do not
 escape.
 
-The remedy is that we allow the `local_` keyword to also appear on
+The remedy is that we allow the `local_` keyword to appear on
 function parameters:
 
 ```ocaml
@@ -106,13 +100,13 @@ val uses_callback : f:(local_ int Foo.Table.t -> 'a) -> 'a
 
 ## Inference
 
-The examples above use the `local_` keyword to mark local
+The examples above use the `stack_` keyword to mark stack
 allocations. In fact, this is not necessary, and the compiler will use
-local allocations by default where possible.
+stack allocations by default where possible.
 
-The only effect of the keyword on e.g. a let binding is to change the
-behavior for escaping values: if the bound value looks like it escapes
-and therefore cannot be locally allocated, then without the keyword
+The only effect of the keyword on an allocation is to change the
+behavior for escaping values: if the allocation looks like it escapes
+and therefore cannot be stack-allocated, then without the keyword
 the compiler will allocate this value on the GC heap as usual, while
 with the keyword it will instead report an error.
 
@@ -128,15 +122,15 @@ mark the local parameter in the other module's mli.
 ## More control
 
 There are a number of other features that allow more precise control
-over which values are locally allocated, including:
+over which values are stack-allocated, including:
 
   - **Local closures**
 
     ```ocaml
-    let local_ f a b c = ...
+    let stack_ f a b c = ...
     ```
 
-    defines a function `f` whose closure is itself locally allocated.
+    defines a function `f` whose closure is itself stack-allocated.
 
   - **Local-returning functions**
 
@@ -145,7 +139,7 @@ over which values are locally allocated, including:
       ...
     ```
 
-    defines a function `f` which returns local allocations into its
+    defines a function `f` which returns local values into its
     caller's region.
 
   - **Global fields**
@@ -154,8 +148,8 @@ over which values are locally allocated, including:
     type 'a t = { global_ g : 'a }
     ```
 
-    defines a record type `t` whose `g` field is always known to be on
-    the GC heap (and may therefore freely escape regions), even though
-    the record itself may be locally allocated.
+    defines a record type `t` whose `g` field is always known to be `global`
+    (and thus on the GC heap and may freely escape regions), even though
+    the record itself may be `local`.
 
 For more details, read [the reference](./reference.md).