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.

However, if you are implementing AssemblyScript into your own engine and, for example, create your own objects externally, it is necessary to account for a managed object's runtime header. In C, this could look like:

typedef struct {
  uint32_t classId;
  uint32_t payloadSize;
} HALF_HEADER;

typedef struct {
  HALF_HEADER header;
  size_t reserved1;
  size_t reserved2;
} FULL_HEADER;

#define HEADER FULL_HEADER

typedef struct {
  HEADER __header;
  // ...
} MyClass ;

with the define either substituting HEADER with HALF_HEADER if no GC is expected to be present or FULL_HEADER otherwise. Now, when a managed object is created externally, both its classId and payloadSize must be inserted before handing the reference over to AssemblyScript. The classId can be obtained from a dummy object instantiated on the AssemblyScript side for example, while the payloadSize is the size of the object excluding the runtime header.