docs

cli/asc.json

@@ -86,7 +86,9 @@
       "Specifies the runtime implementation to include in the program.",
       "",
       " full  Default runtime based on TLSF and reference counting.",
+      " half  Same as 'full', but not exported to the host.",
       " stub  Minimal stub implementation without free/GC support.",
+      " none  Same as 'stub', but not exported to the host.",
       ""
     ],
     "type": "s",

std/assembly/rt/README.md

@@ -3,8 +3,6 @@ The AssemblyScript Runtime
 
 The runtime provides the functionality necessary to dynamically allocate and deallocate memory of objects, arrays and buffers, as well as keep track of references that are no longer used.
 
-It is based on [the TLSF memory manager](./tlsf.ts) and [a pure reference counting garbage collector](./pure.ts).
-
 Interface
 ---------
 
@@ -18,8 +16,8 @@ Interface
 * **__free**(ref: `usize`): `void`<br />
   Frees a dynamically allocated chunk of memory by its address.
 
-* **__retain**(ref: `usize`): `void`<br />
-  Retains a reference to an instance of a reference type. The instance doesn't become collected as long as there's at least one retained reference.
+* **__retain**(ref: `usize`): `usize`<br />
+  Retains a reference to an instance of a reference type. The instance doesn't become collected as long as there's at least one retained reference. Returns the retained reference.
 
 * **__release**(ref: `usize`): `void`<br />
   Releases a reference to an instance of a reference type. The instance is considered for collection once all references to it have been released.
@@ -27,31 +25,40 @@ Interface
 * **__collect**(): `void`<br />
   Forces a full garbage collection cycle. By default this means that reference cycles are resolved and possibly collected.
 
+### Internals
+
+* **__retainRelease**(newRef: `usize`, oldRef: `usize`): `usize`<br />
+  Retains a reference to an instance of a reference type while releasing the reference it replaces. Returns the retained reference.
+
 * **__visit**(ref: `usize`, cookie: `u32`): `void`<br />
   Concrete visitor implementation called during traversal. Cookie can be used to indicate one of multiple operations.
 
-Built-ins
----------
+### Built-ins
 
-The following functions are generated by the compiler based on compile-time information that wouldn't be available or inefficient to provide otherwise.
-
-* **__info**(id: `u32`): `void`<br />
+* **__typeinfo**(id: `u32`): `RTTIFlags`<br />
   Obtains the runtime type information for objects with the specified runtime id. Runtime type information is a set of flags indicating whether a reference type is managed, an array or similar, and what the relevant alignments when creating an instance are etc.
 
-* **__visit_globals**(cookie: `u32`)<br />
+* **__visit_globals**(cookie: `u32`): `void`<br />
   Calls `__visit` on each global that is of a reference type. Not used anymore (originally provided to support tracing GCs) but still here for possible future use.
 
-* **__visit_members**(ref: `usize`, cookie: `u32`)<br />
+* **__visit_members**(ref: `usize`, cookie: `u32`): `void`<br />
   Calls `__visit` on each member of the instance pointed to by `ref` that is of a reference type.
 
-Stub
-----
+Full/half
+---------
 
-A fully functional yet minimal (as in code size) [stub implementation](./index-stub.ts) that provides dynamic memory allocation but no deallocation. Useful for prototyping or very short-lived programs with hardly any memory footprint. The [none implementation](./index-none.ts) is the same as the stub implementation without any runtime exports.
+The [full](./index-full.ts) runtime is based on [the TLSF memory manager](./tlsf.ts) and [a pure reference counting garbage collector](./pure.ts) and provides all the functionality necessary. The [half](./index-half.ts) alias is essentially the same, but doesn't expose the runtime API so unused runtime code can be DCE'ed.
+
+Stub/none
+---------
+
+The [stub](./index-stub.ts) runtime, though fully functional, provides minimal dynamic memory allocation but no deallocation. Useful for prototyping or very short-lived programs with hardly any memory footprint. The [none](./index-none.ts) alias is the same, but doesn't expose the runtime API so unused runtime code can be DCE'ed.
 
 Integration notes
 -----------------
 
+**NOTE:** Subject to change once local handling has been figured out.
+
 Working with the runtime internals within standard library code can be tricky and requires knowledge of where the compiler will insert runtime calls automatically. For example, whenever a value of a reference type is assigned to a local, a global or a field, the compiler *might* insert a `__retain` call, respectively whenever such a value becomes unassigned from one, *might* insert a `__release` call. When a value is handled as an `usize` (i.e. when it comes from `__alloc` or is `changetype<usize>`ed), no such insertion happens (afterwards), but as soon as a `changetype<RefType>`ed (again), the side-effects introduced by automatic insertion must be understood.
 
 A `__retain` call is inserted when a value of a reference type

std/assembly/rt/index-half.ts

@@ -0,0 +1 @@
+import "rt/index-full";