Runtime

---

NOTE: This is a work in progress and the respective PR has not yet been merged into master.

---

AssemblyScript provides a set of runtime templates to automatically include support for managed objects when compiling a program. As the name says, a runtime template provides functionality that performs certain operations, that cannot be performed at compile time, during runtime, like, for example:

• Include a memory allocator to be able to use new expressions / instantiate managed classes
• Include a garbage collector that either traces or counts the references of unreachable objects

Previous versions of the compiler didn't include any runtime functionality by default, leaving it up to the developer to import relevant implementations manually, while newer versions of the compiler include a default runtime suitable for most tasks. The runtime template to include can be specified with the --runtime flag:

• --runtime default
  The runtime that is included by default, consisting of the TLSF memory allocator and the ITCM garbage collector.

• --runtime arena
  A very small prototyping runtime without free/GC support. Equivalent to just importing allocator/arena.

• --runtime none
  Just basic runtime functionality like instanceof. Equivalent to the initial bare bones behaviour.

The --runtime option can also be used to specify an additional entry file relative to baseDir that sets up custom runtime functionality, i.e. picks another memory allocator or garbage collector, provides additional global functions, you name it.

Runtime header

In order to provide basic functionality like instanceof, each managed object (not annotated @unmanaged) has a hidden header that contains the necessary information. Usually, one doesn't come into contact with the runtime header because it is "hidden", that means that it is located before the address that a reference points at.

╒════════════════════ Managed header (32-bit) ══════════════════╕
   3                   2                   1
 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0  bits
├─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤             ┐
│   .classId         unique id of the respective class          │
├───────────────────────────────────────────────────────────────┤
│   .payloadLength   size of 'data'                             │
├───────────────────────────────────────────────────────────────┤ SIZE w/o GC ┘
│   .reserved1       reserved space for GC                      │ ◄─┐
├───────────────────────────────────────────────────────────────┤  usize
│   .reserved2       reserved space for GC                      │ ◄─┘
╞═══════════════════════════════════════════════════════════════╡ SIZE w/ GC  ┘
│          ... payload, reference points here ...               |

The reserved fields are only present if a garbage collector has been included, so the header has a size of 8 bytes in WASM32 without a GC respectively 16 bytes in WASM32 with a GC.